package module
Version: v1.4.0 Latest Latest

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

Go to latest
Published: Oct 6, 2019 License: MIT Imports: 21 Imported by: 2



An extendable TURN server written in Go

Pion TURN Slack Widget Waffle board
Build Status GoDoc Coverage Status Go Report Card Codacy Badge

A TURN server written in Go that is designed to be scalable, extendable and embeddable out of the box. For simple use cases it only requires downloading 1 static binary, and setting 3 options.

See DESIGN.md for the the features it offers, and future goals.

Quick Start

If you want just a simple TURN server with a few static usernames simple-turn will perfectly suit your purposes. If you have custom requirements such as a database proceed to extending.

simple-turn is a single static binary, and all config is driven by environment variables. On a fresh Linux AWS instance these are all the steps you would need.

$ wget -q https://github.com/pion/turn/releases/download/1.0.3/simple-turn-linux-amd64
$ chmod +x simple-turn-linux-amd64
$ export USERS='user=password foo=bar'
$ export REALM=my-server.com
$ export UDP_PORT=3478
$ ./simple-turn-linux-amd64

To explain what every step does

  • Download simple-turn for Linux x64, see release for other platforms
  • Make it executable
  • Configure auth, in the form of USERNAME=PASSWORD USERNAME=PASSWORD with no limits
  • Set your realm, this is the public URL or name of your server
  • Set the port you listen on, 3478 is the default port for TURN

That is it! Then to use your new TURN server your WebRTC config would look like

{ iceServers: [{
  urls: "turn:YOUR_SERVER"
  username: "user",
  credential: "password"

If you are using Windows you would set these values in Powershell by doing. Also make sure your firewall is configured properly.

> $env:USERS = "user=password foo=bar"
> $env:REALM = "my-server.com"
> $env:UDP_PORT = 3478


See simple-turn

pion-turn can be configured by implementing these callbacks and by passing these arguments

All that simple-turn does is take environment variables, and then uses the same API.


For developing a Dockerfile is available with features like hot-reloads, and is meant to be volume mounted. Make sure you also have github.com/pion/pkg in your path, or you can exclude the second volume mount.

This is only meant for development, see demo-conference to see TURN usage as a user.

docker build -t turn .
docker run -v $(pwd):/usr/local/src/github.com/pion/turn -v $(pwd)/../pkg:/usr/local/src/github.com/pion/pkg turn

Currently only Linux is supported until Docker supports full (host <-> container) networking on Windows/OSX





Pion has an active community on the Golang Slack. Sign up and join the #pion channel for discussions and support. You can also use Pion mailing list.

We are always looking to support your projects. Please reach out if you have something to build!


Check out the CONTRIBUTING.md to join the group of amazing people making this project possible:


MIT License - see LICENSE.md for full text




This section is empty.


This section is empty.


This section is empty.


type AuthHandler added in v1.2.0

type AuthHandler func(username string, srcAddr net.Addr) (password string, ok bool)

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

type Client

type Client struct {
	// contains filtered or unexported fields

Client is a STUN server client

func NewClient added in v1.2.0

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

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

func (*Client) Allocate added in v1.3.0

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

Allocate sends a TURN allocation request to the given transport address

func (*Client) Close added in v1.3.0

func (c *Client) Close()

Close closes this client

func (*Client) HandleInbound added in v1.3.0

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

HandleInbound handles data received. This method handles incoming packet demultiplex it by the source address and the types of the message. This return a booleen (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 added in v1.3.0

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 added in v1.3.0

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

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

func (*Client) PerformTransaction added in v1.3.0

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

PerformTransaction performs STUN transaction

func (*Client) Realm added in v1.3.0

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

Realm return realm

func (*Client) STUNServerAddr added in v1.3.0

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

STUNServerAddr return the STUN server address

func (*Client) SendBindingRequest added in v1.3.0

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

SendBindingRequest sends a new STUN request to the STUN server

func (*Client) SendBindingRequestTo added in v1.3.0

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

SendBindingRequestTo sends a new STUN request to the given transport address

func (*Client) TURNServerAddr added in v1.3.0

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

TURNServerAddr return the TURN server address

func (*Client) Username added in v1.3.0

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

Username returns username

func (*Client) WriteTo added in v1.3.0

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

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

type ClientConfig added in v1.2.0

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

ClientConfig is a bag of config parameters for Client.

type STUNConn added in v1.4.0

type STUNConn struct {
	// contains filtered or unexported fields

STUNConn wraps a net.Conn and implements net.PacketConn by being STUN aware and packetizing the stream

func NewSTUNConn added in v1.4.0

func NewSTUNConn(nextConn net.Conn) *STUNConn

NewSTUNConn creates a STUNConn

func (*STUNConn) Close added in v1.4.0

func (s *STUNConn) Close() error

Close implements Close from net.PacketConn

func (*STUNConn) LocalAddr added in v1.4.0

func (s *STUNConn) LocalAddr() net.Addr

LocalAddr implements LocalAddr from net.PacketConn

func (*STUNConn) ReadFrom added in v1.4.0

func (s *STUNConn) ReadFrom(p []byte) (n int, addr net.Addr, err error)

ReadFrom implements ReadFrom from net.PacketConn

func (*STUNConn) SetDeadline added in v1.4.0

func (s *STUNConn) SetDeadline(t time.Time) error

SetDeadline implements SetDeadline from net.PacketConn

func (*STUNConn) SetReadDeadline added in v1.4.0

func (s *STUNConn) SetReadDeadline(t time.Time) error

SetReadDeadline implements SetReadDeadline from net.PacketConn

func (*STUNConn) SetWriteDeadline added in v1.4.0

func (s *STUNConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements SetWriteDeadline from net.PacketConn

func (*STUNConn) WriteTo added in v1.4.0

func (s *STUNConn) WriteTo(p []byte, addr net.Addr) (n int, err error)

WriteTo implements WriteTo from net.PacketConn

type Sender added in v1.3.0

type Sender func(conn net.PacketConn, addr net.Addr, attrs ...stun.Setter) error

Sender is responsible for building a message and sending it to the given addr.

type Server

type Server struct {
	// contains filtered or unexported fields

Server is an instance of the Pion TURN server

func NewServer added in v1.2.0

func NewServer(config *ServerConfig) *Server

NewServer creates the Pion TURN server

func (*Server) AddExternalIPAddr added in v1.3.5

func (s *Server) AddExternalIPAddr(mapping string) error

AddExternalIPAddr adds a mapping to an external IP address. This is useful when the TURN server is behind a 1-to-1 NAT, or a D-NAT (which is typical when hosting on AWS EC2). The argument should be a dotted-decimal representation of external IP address. If there is more than on IP address, the argument should be a cancatenation of external IP and local IP delimited by a '/'. Ex 1: "" Ex 2: "" By default, no address mapping is used. This method must be called before calling Start().

func (*Server) AddListeningIPAddr added in v1.2.0

func (s *Server) AddListeningIPAddr(addrStr string) error

AddListeningIPAddr adds a listening IP address. If not specified, it will automatically assigns the listening IP addresses from the system. This method must be called before calling Start().

func (*Server) AddRelayIPAddr added in v1.2.1

func (s *Server) AddRelayIPAddr(addrStr string) error

AddRelayIPAddr adds a listening IP address. Note: current implementation can have only one relay IP address. If not specified, it will automatically assigns the relay IP addresses from the system. This method must be called before calling Start().

func (*Server) Close added in v1.2.0

func (s *Server) Close() error

Close closes the connection.

func (*Server) Start added in v1.2.0

func (s *Server) Start() error

Start starts the server.

type ServerConfig added in v1.2.0

type ServerConfig struct {
	// Realm sets the realm for this server
	Realm string
	// AuthHandler is the handler called on each incoming auth requests.
	AuthHandler AuthHandler
	// ChannelBindTimeout sets the lifetime of channel binding. Defaults to 10 minutes.
	ChannelBindTimeout time.Duration
	// ListeningPort sets the listening port number. Defaults to 3478.
	ListeningPort int
	// LoggerFactory must be set for logging from this server.
	LoggerFactory logging.LoggerFactory
	// Net is used by pion developers. Do not use in your application.
	Net *vnet.Net
	// Software is the STUN SOFTWARE attribute. Useful for debugging purpose.
	Software string
	// Sender is a custom implementation of the request Sender.
	Sender Sender

ServerConfig is a bag of config parameters for Server.


Path Synopsis
Package proto implements RFC 5766 Traversal Using Relays around NAT.
Package proto implements RFC 5766 Traversal Using Relays around NAT.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL