turn

package module
v5.0.1 Latest Latest
Warning

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

 Go to latest Published: Jan 17, 2026 License: MIT Imports: 25 Imported by: 0

README

Pion TURN
Pion TURN

A toolkit for building TURN clients and servers in Go

Pion TURN join us on Discord Follow us on Bluesky
GitHub Workflow Status Go Reference Coverage Status Go Report Card


Pion TURN is a Go toolkit for building TURN servers and clients. We wrote it to solve problems we had when building RTC projects.

  • Deployable - Use modern tooling of the Go ecosystem. Stop generating config files.
  • Embeddable - Include pion/turn in your existing applications. No need to manage another service.
  • Extendable - TURN as an API so you can easily integrate with your existing monitoring and metrics.
  • Maintainable - pion/turn is simple and well documented. Designed for learning and easy debugging.
  • Portable - Quickly deploy to multiple architectures/platforms just by setting an environment variable.
  • Safe - Stability and safety is important for network services. Go provides everything we need.
  • Scalable - Create allocations and mutate state at runtime. Designed to make scaling easy.

Using

pion/turn is an API for building STUN/TURN clients and servers, not a binary you deploy then configure. It may require copying our examples and making minor modifications to fit your need, no knowledge of Go is required however. You may be able to download the pre-made binaries of our examples if you wish to get started quickly.

The advantage of this is that you don't need to deal with complicated config files, or custom APIs to modify the state of Pion TURN. After you instantiate an instance of a Pion TURN server or client you interact with it like any library. The quickest way to get started is to look at the examples or GoDoc

Examples

We try to cover most common use cases in examples. If more examples could be helpful please file an issue, we are always looking to expand and improve pion/turn to make it easier for developers.

To build any example you just need to run go build in the directory of the example you care about. It is also very easy to cross compile Go programs.

You can also see pion/turn usage in pion/ice

FAQ

Also take a look at the Pion WebRTC FAQ

Will pion/turn also act as a STUN server?

Yes.

How do I implement token-based authentication?

Replace the username with a token in the AuthHandler. The password sent by the client can be any non-empty string, as long as it matches that used by the GenerateAuthKey function.

How do I implement mTLS (mutual TLS) authentication?

You can use client certificates for authentication by checking the TLS connection state in your AuthHandler. See the mutual-tls-auth example for a complete implementation that validates client certificates and matches the certificate's Common Name to the TURN username.

Will WebRTC prioritize using STUN over TURN?

Yes.

RFCs

Implemented

Roadmap

The library is used as a part of our WebRTC implementation. Please refer to that roadmap to track our major milestones.

Community

Pion has an active community on the Discord.

Follow the Pion Bluesky or Pion Twitter for project updates and important WebRTC news.

We are always looking to support your projects. Please reach out if you have something to build! If you need commercial support or don't want to use public methods you can contact us at team@pion.ly

Contributing

Check out the contributing wiki to join the group of amazing people making this project possible

License

MIT License - see LICENSE for full text

Documentation

Overview

Package turn contains the public API for pion/turn, a toolkit for building TURN clients and servers

Index

Constants

View Source 
const (
	RequestedAddressFamilyIPv4 = proto.RequestedFamilyIPv4
	RequestedAddressFamilyIPv6 = proto.RequestedFamilyIPv6
)

Values for RequestedAddressFamily as defined in RFC 6156 Section 4.1.1.

Variables

This section is empty.

Functions

func DefaultPermissionHandler 

func DefaultPermissionHandler(net.Addr, net.IP) (ok bool)

DefaultPermissionHandler is convince function that grants permission to all peers.

func GenerateAuthKey 

func GenerateAuthKey(username, realm, password string) []byte

GenerateAuthKey is a convenience function to easily generate keys in the format used by AuthHandler.

func GenerateLongTermCredentials 

func GenerateLongTermCredentials(sharedSecret string, duration time.Duration) (string, string, error)

GenerateLongTermCredentials can be used to create credentials valid for [duration] time.

func GenerateLongTermTURNRESTCredentials 

func GenerateLongTermTURNRESTCredentials(sharedSecret string, user string, duration time.Duration) (
	string,
	string,
	error,
)

GenerateLongTermTURNRESTCredentials can be used to create credentials valid for [duration] time.

Types

type AllocateConnConfig 

type AllocateConnConfig = allocation.AllocateConnConfig

AllocateConnConfig defines the parameters passed to the TCP connection generator.

type AllocateListenerConfig 

type AllocateListenerConfig = allocation.AllocateListenerConfig

AllocateListenerConfig defines the parameters passed to the relay address allocator.

type AuthHandler 

type AuthHandler = auth.AuthHandler

AuthHandler is a callback used to handle incoming auth requests, allowing users to customize Pion TURN with custom behavior.

func LongTermTURNRESTAuthHandler 

func LongTermTURNRESTAuthHandler(sharedSecret string, logger logging.LeveledLogger) AuthHandler

LongTermTURNRESTAuthHandler returns a turn.AuthAuthHandler that can be used to authenticate time-windowed ephemeral credentials generated by the TURN REST API as described in https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00

The supported format of is timestamp:username, where username is an arbitrary user id and the timestamp specifies the expiry of the credential.

func NewLongTermAuthHandler 

func NewLongTermAuthHandler(sharedSecret string, logger logging.LeveledLogger) AuthHandler

NewLongTermAuthHandler returns a turn.AuthAuthHandler used with Long Term (or Time Windowed) Credentials. See: https://datatracker.ietf.org/doc/html/rfc8489#section-9.2 .

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a STUN server client.

func NewClient 

func NewClient(config *ClientConfig) (*Client, error)

NewClient returns a new Client instance. listeningAddress is the address and port to listen on, default "0.0.0.0:0".

func (*Client) Allocate 

func (c *Client) Allocate() (net.PacketConn, error)

Allocate sends a TURN allocation request to the given transport address.

func (*Client) AllocateTCP 

func (c *Client) AllocateTCP() (*client.TCPAllocation, error)

AllocateTCP creates a new TCP allocation at the TURN server.

func (*Client) Close 

func (c *Client) Close()

Close closes this client.

func (*Client) CreatePermission 

func (c *Client) CreatePermission(addrs ...net.Addr) error

CreatePermission Issues a CreatePermission request for the supplied addresses as described in https://datatracker.ietf.org/doc/html/rfc5766#section-9

func (*Client) HandleInbound 

func (c *Client) HandleInbound(data []byte, from net.Addr) (bool, error)

HandleInbound handles data received. This method handles incoming packet de-multiplex it by the source address and the types of the message. This return a boolean (handled or not) and if there was an error. Caller should check if the packet was handled by this client or not. If not handled, it is assumed that the packet is application data. If an error is returned, the caller should discard the packet regardless.

func (*Client) Listen 

func (c *Client) Listen() error

Listen will have this client start listening on the conn provided via the config. This is optional. If not used, you will need to call HandleInbound method to supply incoming data, instead.

func (*Client) OnDeallocated 

func (c *Client) OnDeallocated(net.Addr)

OnDeallocated is called when de-allocation of relay address has been complete. (Called by UDPConn).

func (*Client) PerformTransaction 

func (c *Client) PerformTransaction(msg *stun.Message, to net.Addr, ignoreResult bool) (client.TransactionResult,
	error,
)

PerformTransaction performs STUN transaction.

func (*Client) Realm 

func (c *Client) Realm() stun.Realm

Realm return realm.

func (*Client) STUNServerAddr 

func (c *Client) STUNServerAddr() net.Addr

STUNServerAddr return the STUN server address.

func (*Client) SendBindingRequest 

func (c *Client) SendBindingRequest() (net.Addr, error)

SendBindingRequest sends a new STUN request to the STUN server.

func (*Client) SendBindingRequestTo 

func (c *Client) SendBindingRequestTo(to net.Addr) (net.Addr, error)

SendBindingRequestTo sends a new STUN request to the given transport address.

func (*Client) TURNServerAddr 

func (c *Client) TURNServerAddr() net.Addr

TURNServerAddr return the TURN server address.

func (*Client) Username 

func (c *Client) Username() stun.Username

Username returns username.

func (*Client) WriteTo 

func (c *Client) WriteTo(data []byte, to net.Addr) (int, error)

WriteTo sends data to the specified destination using the base socket.

type ClientConfig 

type ClientConfig struct {
	STUNServerAddr string // STUN server address (e.g. "stun.abc.com:3478")
	TURNServerAddr string // TURN server address (e.g. "turn.abc.com:3478")
	Username       string
	Password       string
	Realm          string
	Software       string
	RTO            time.Duration
	Conn           net.PacketConn // Listening socket (net.PacketConn)
	Net            transport.Net
	LoggerFactory  logging.LoggerFactory

	// PermissionTimeout sets the refresh interval of permissions. Defaults to 2 minutes.
	PermissionRefreshInterval time.Duration

	// RequestedAddressFamily is the address family to request in allocations (IPv4 or IPv6).
	// If not specified (zero value), the client will attempt to infer from the PacketConn's
	// local address, falling back to IPv4 if inference fails. See RFC 6156.
	RequestedAddressFamily RequestedAddressFamily
	// contains filtered or unexported fields
}

ClientConfig is a bag of config parameters for Client.

type EventHandler 

type EventHandler = allocation.EventHandler

EventHandler is a set of callbacks that the server will call at certain hook points during an allocation's lifecycle.

type ListenerConfig 

type ListenerConfig struct {
	Listener net.Listener

	// When an allocation is generated the RelayAddressGenerator
	// creates the net.Listener and returns the IP/Port it is available at
	RelayAddressGenerator RelayAddressGenerator

	// PermissionHandler is a callback to filter peer addresses. Can be set as nil, in which
	// case the DefaultPermissionHandler is automatically instantiated to admit all peer
	// connections
	PermissionHandler PermissionHandler
}

ListenerConfig is a single net.Listener to accept connections on. This will be used for TCP, TLS and DTLS listeners.

type PacketConnConfig 

type PacketConnConfig struct {
	PacketConn net.PacketConn

	// When an allocation is generated the RelayAddressGenerator
	// creates the net.PacketConn and returns the IP/Port it is available at
	RelayAddressGenerator RelayAddressGenerator

	// PermissionHandler is a callback to filter peer addresses. Can be set as nil, in which
	// case the DefaultPermissionHandler is automatically instantiated to admit all peer
	// connections
	PermissionHandler PermissionHandler
}

PacketConnConfig is a single net.PacketConn to listen/write on. This will be used for UDP listeners.

type PermissionHandler 

type PermissionHandler func(clientAddr net.Addr, peerIP net.IP) (ok bool)

PermissionHandler is a callback to filter incoming CreatePermission and ChannelBindRequest requests based on the client IP address and port and the peer IP address the client intends to connect to. If the client is behind a NAT then the filter acts on the server reflexive ("mapped") address instead of the real client IP address and port. Note that TURN permissions are per-allocation and per-peer-IP-address, to mimic the address-restricted filtering mechanism of NATs that comply with [RFC4787], see https://tools.ietf.org/html/rfc5766#section-2.3.

type QuotaHandler 

type QuotaHandler func(username, realm string, srcAddr net.Addr) (ok bool)

QuotaHandler is a callback allows allocations to be rejected when a per-user quota is exceeded. If the callback returns true the allocation request is accepted, otherwise it is rejected and a 486 (Allocation Quota Reached) error is returned to the user.

type RelayAddressGenerator 

type RelayAddressGenerator interface {
	// Validate confirms that the RelayAddressGenerator is properly initialized
	Validate() error

	// Allocate a PacketConn (UDP) RelayAddress
	AllocatePacketConn(AllocateListenerConfig) (net.PacketConn, net.Addr, error)

	// Allocate a Listener (TCP) RelayAddress
	AllocateListener(AllocateListenerConfig) (net.Listener, net.Addr, error)

	// Allocate a Conn (TCP) relay connection
	AllocateConn(AllocateConnConfig) (net.Conn, error)
}

RelayAddressGenerator is used to generate a RelayAddress when creating an allocation. You can use one of the provided ones or provide your own.

type RelayAddressGeneratorNone 

type RelayAddressGeneratorNone struct {
	// Address is passed to Listen/ListenPacket when creating the Relay
	Address string

	Net transport.Net
}

RelayAddressGeneratorNone returns the listener with no modifications.

func (*RelayAddressGeneratorNone) AllocateConn 

func (r *RelayAddressGeneratorNone) AllocateConn(conf AllocateConnConfig) (net.Conn, error)

AllocateConn creates a new outgoing TCP connection bound to the relay address to send traffic to a peer.

func (*RelayAddressGeneratorNone) AllocateListener 

func (r *RelayAddressGeneratorNone) AllocateListener(conf AllocateListenerConfig) (net.Listener, net.Addr, error)

AllocateListener generates a new Listener to receive traffic on and the IP/Port to populate the allocation response with.

func (*RelayAddressGeneratorNone) AllocatePacketConn 

func (r *RelayAddressGeneratorNone) AllocatePacketConn(conf AllocateListenerConfig) (
	net.PacketConn,
	net.Addr,
	error,
)

AllocatePacketConn generates a new PacketConn to receive traffic on and the IP/Port to populate the allocation response with.

func (*RelayAddressGeneratorNone) Validate 

func (r *RelayAddressGeneratorNone) Validate() error

Validate is called on server startup and confirms the RelayAddressGenerator is properly configured.

type RelayAddressGeneratorPortRange 

type RelayAddressGeneratorPortRange struct {
	// RelayAddress is the IP returned to the user when the relay is created
	RelayAddress net.IP

	// MinPort the minimum port to allocate
	MinPort uint16
	// MaxPort the maximum (inclusive) port to allocate
	MaxPort uint16

	// MaxRetries the amount of tries to allocate a random port in the defined range
	MaxRetries int

	// Rand the random source of numbers
	Rand randutil.MathRandomGenerator

	// Address is passed to Listen/ListenPacket when creating the Relay
	Address string

	Net transport.Net
}

RelayAddressGeneratorPortRange can be used to only allocate connections inside a defined port range. Similar to the RelayAddressGeneratorStatic a static ip address can be set.

func (*RelayAddressGeneratorPortRange) AllocateConn 

func (r *RelayAddressGeneratorPortRange) AllocateConn(conf AllocateConnConfig) (net.Conn, error)

AllocateConn creates a new outgoing TCP connection bound to the relay address to send traffic to a peer.

func (*RelayAddressGeneratorPortRange) AllocateListener 

func (r *RelayAddressGeneratorPortRange) AllocateListener(
	conf AllocateListenerConfig,
) (net.Listener, net.Addr, error)

AllocateListener generates a new Listener to receive traffic on and the IP/Port to populate the allocation response with.

func (*RelayAddressGeneratorPortRange) AllocatePacketConn 

func (r *RelayAddressGeneratorPortRange) AllocatePacketConn(
	conf AllocateListenerConfig,
) (net.PacketConn, net.Addr, error)

AllocatePacketConn generates a new PacketConn to receive traffic on and the IP/Port to populate the allocation response with.

func (*RelayAddressGeneratorPortRange) Validate 

func (r *RelayAddressGeneratorPortRange) Validate() error

Validate is called on server startup and confirms the RelayAddressGenerator is properly configured.

type RelayAddressGeneratorStatic 

type RelayAddressGeneratorStatic struct {
	// RelayAddress is the IP returned to the user when the relay is created
	RelayAddress net.IP

	// Address is passed to Listen/ListenPacket when creating the Relay
	Address string

	Net transport.Net
}

RelayAddressGeneratorStatic can be used to return static IP address each time a relay is created. This can be used when you have a single static IP address that you want to use.

func (*RelayAddressGeneratorStatic) AllocateConn 

func (r *RelayAddressGeneratorStatic) AllocateConn(conf AllocateConnConfig) (net.Conn, error)

AllocateConn creates a new outgoing TCP connection bound to the relay address to send traffic to a peer.

func (*RelayAddressGeneratorStatic) AllocateListener 

func (r *RelayAddressGeneratorStatic) AllocateListener(conf AllocateListenerConfig) (net.Listener, net.Addr, error)

AllocateListener generates a new Listener to receive traffic on and the IP/Port to populate the allocation response with.

func (*RelayAddressGeneratorStatic) AllocatePacketConn 

func (r *RelayAddressGeneratorStatic) AllocatePacketConn(
	conf AllocateListenerConfig,
) (net.PacketConn, net.Addr, error)

AllocatePacketConn generates a new PacketConn to receive traffic on and the IP/Port to populate the allocation response with.

func (*RelayAddressGeneratorStatic) Validate 

func (r *RelayAddressGeneratorStatic) Validate() error

Validate is called on server startup and confirms the RelayAddressGenerator is properly configured.

type RequestAttributes 

type RequestAttributes = auth.RequestAttributes

RequestAttributes represents attributes of a TURN request which may be useful for authorizing the underlying request.

type RequestedAddressFamily 

type RequestedAddressFamily = proto.RequestedAddressFamily

RequestedAddressFamily represents the REQUESTED-ADDRESS-FAMILY Attribute as defined in RFC 6156 Section 4.1.1.

type STUNConn 

type STUNConn = proto.STUNConn

func NewSTUNConn 

func NewSTUNConn(nextConn net.Conn) *STUNConn

NewSTUNConn creates a STUNConn.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server is an instance of the Pion TURN Server.

func NewServer 

func NewServer(config ServerConfig) (*Server, error)

NewServer creates the Pion TURN server.

func (*Server) AllocationCount 

func (s *Server) AllocationCount() int

AllocationCount returns the number of active allocations. It can be used to drain the server before closing.

func (*Server) Close 

func (s *Server) Close() error

Close stops the TURN Server. It cleans up any associated state and closes all connections it is managing.

type ServerConfig 

type ServerConfig struct {
	// PacketConnConfigs and ListenerConfigs are a list of all the turn listeners
	// Each listener can have custom behavior around the creation of Relays
	PacketConnConfigs []PacketConnConfig
	ListenerConfigs   []ListenerConfig

	// LoggerFactory must be set for logging from this server.
	LoggerFactory logging.LoggerFactory

	// Realm sets the realm for this server
	Realm string

	// AuthHandler is a callback used to handle incoming auth requests,
	// allowing users to customize Pion TURN with custom behavior
	AuthHandler AuthHandler

	// QuotaHandler is a callback used to reject new allocations when a
	// per-user quota is exceeded.
	QuotaHandler QuotaHandler

	// EventHandlers is a set of callbacks for tracking allocation lifecycle.
	EventHandler EventHandler

	// ChannelBindTimeout sets the lifetime of channel binding. Defaults to 10 minutes.
	ChannelBindTimeout time.Duration

	// PermissionTimeout sets the lifetime of permission. Defaults to 10 minutes.
	PermissionTimeout time.Duration

	// AllocationLife sets the lifetime of allocation. Defaults to 10 minutes.
	AllocationLifetime time.Duration

	// Sets the server inbound MTU(Maximum transmition unit). Defaults to 1600 bytes.
	InboundMTU int
}

ServerConfig configures the Pion TURN Server.

Source Files

View all Source files

Directories

Path Synopsis
examples
lt-cred-generator command
Package main implements a CLI tool for generating long-term credentials.
 Package main implements a CLI tool for generating long-term credentials.
mutual-tls-auth/turn-client command
Package main implements a TURN client with TLS certificate-based authentication
 Package main implements a TURN client with TLS certificate-based authentication
mutual-tls-auth/turn-server command
Package main implements an example TURN server with TLS certificate-based authentication
 Package main implements an example TURN server with TLS certificate-based authentication
stun-only-server command
Package main implements a simple TURN server
 Package main implements a simple TURN server
turn-client/ipv6 command
Package main implements a TURN client using UDP with IPv6 support (RFC 6156)
 Package main implements a TURN client using UDP with IPv6 support (RFC 6156)
turn-client/tcp command
Package main implements a TURN client with support for TCP
 Package main implements a TURN client with support for TCP
turn-client/tcp-alloc command
Package main implements a TURN client with support for TCP
 Package main implements a TURN client with support for TCP
turn-client/tls command
Package main implements a TURN client with TLS support
 Package main implements a TURN client with TLS support
turn-client/udp command
Package main implements a TURN client using UDP
 Package main implements a TURN client using UDP
turn-server/add-software-attribute command
Package main implements a TURN server adding a software attribute.
 Package main implements a TURN server adding a software attribute.
turn-server/bw-quota command
Package main implements a TURN server with per-user bandwidth quotas.
 Package main implements a TURN server with per-user bandwidth quotas.
turn-server/ipv6 command
Package main implements a simple TURN server with IPv6 support (RFC 6156)
 Package main implements a simple TURN server with IPv6 support (RFC 6156)
turn-server/log command
Package main implements a TURN server with logging.
 Package main implements a TURN server with logging.
turn-server/lt-cred command
Package main implements a TURN server using long-term credentials.
 Package main implements a TURN server using long-term credentials.
turn-server/lt-cred-turn-rest command
Package main implements a TURN server using ephemeral credentials.
 Package main implements a TURN server using ephemeral credentials.
turn-server/perm-filter command
This example demonstrates the use of a permission handler in the PION TURN server.
 This example demonstrates the use of a permission handler in the PION TURN server.
turn-server/port-range command
Package main implements a TURN server with a specified port range.
 Package main implements a TURN server with a specified port range.
turn-server/simple command
Package main implements a simple TURN server
 Package main implements a simple TURN server
turn-server/simple-multithreaded command
Package main implements a multi-threaded TURN server
 Package main implements a multi-threaded TURN server
turn-server/simple-quota command
Package main implements a simple TURN server with per-user allocation quotas.
 Package main implements a simple TURN server with per-user allocation quotas.
turn-server/tcp command
Package main implements an example TURN server supporting TCP
 Package main implements an example TURN server supporting TCP
turn-server/tls command
Package main implements a TURN server with TLS support
 Package main implements a TURN server with TLS support
internal
allocation
Package allocation contains all CRUD operations for allocations
 Package allocation contains all CRUD operations for allocations
auth
Package auth provides internal authentication / authorization types and utilities for the TURN server.
 Package auth provides internal authentication / authorization types and utilities for the TURN server.
client
Package client implements the API for a TURN client
 Package client implements the API for a TURN client
ipnet
Package ipnet contains helper functions around net and IP
 Package ipnet contains helper functions around net and IP
proto
Package proto implements RFC 5766 Traversal Using Relays around NAT.
 Package proto implements RFC 5766 Traversal Using Relays around NAT.
server
Package server implements the private API to implement a TURN server
 Package server implements the private API to implement a TURN server

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.