turn

README

Pion TURN

An extendable TURN server written in Go

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

Extending

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.

Developing

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

RFCs

Implemented

• RFC 5389: Session Traversal Utilities for NAT (STUN)
• RFC 5766: Traversal Using Relays around NAT (TURN)

Planned

• RFC 6062: Traversal Using Relays around NAT (TURN) Extensions for TCP Allocations
• RFC 6156: Traversal Using Relays around NAT (TURN) Extension for IPv6

Community

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!

Contributing

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

• Michiel De Backker - Documentation
• Ingmar Wittkau - STUN client
• John Bradley - Original Author
• jose nazario - Documentation
• Mészáros Mihály - Documentation
• Mike Santry - Mascot
• Sean DuBois - Original Author
• winds2016 - Windows platform testing
• songjiayang - SongJiaYang
• Yutaka Takeda - vnet
• namreg - Igor German
• Aleksandr Razumov - protocol
• Robert Eperjesi
• Lukas Rezek
• Hugo Arregui
• Aaron France

License

MIT License - see LICENSE.md for full text

Documentation

Index

• type AuthHandler
• type Client
  • func NewClient(config *ClientConfig) (*Client, error)
  • func (c *Client) Allocate() (net.PacketConn, error)
  • func (c *Client) Close()
  • func (c *Client) HandleInbound(data []byte, from net.Addr) (bool, error)
  • func (c *Client) Listen() error
  • func (c *Client) OnDeallocated(relayedAddr net.Addr)
  • func (c *Client) PerformTransaction(msg *stun.Message, to net.Addr, dontWait bool) (client.TransactionResult, error)
  • func (c *Client) Realm() stun.Realm
  • func (c *Client) STUNServerAddr() net.Addr
  • func (c *Client) SendBindingRequest() (net.Addr, error)
  • func (c *Client) SendBindingRequestTo(to net.Addr) (net.Addr, error)
  • func (c *Client) TURNServerAddr() net.Addr
  • func (c *Client) Username() stun.Username
  • func (c *Client) WriteTo(data []byte, to net.Addr) (int, error)
• type ClientConfig
• type STUNConn
  • func NewSTUNConn(nextConn net.Conn) *STUNConn
  • func (s *STUNConn) Close() error
  • func (s *STUNConn) LocalAddr() net.Addr
  • func (s *STUNConn) ReadFrom(p []byte) (n int, addr net.Addr, err error)
  • func (s *STUNConn) SetDeadline(t time.Time) error
  • func (s *STUNConn) SetReadDeadline(t time.Time) error
  • func (s *STUNConn) SetWriteDeadline(t time.Time) error
  • func (s *STUNConn) WriteTo(p []byte, addr net.Addr) (n int, err error)
• type Sender
• type Server
  • func NewServer(config *ServerConfig) *Server
  • func (s *Server) AddExternalIPAddr(mapping string) error
  • func (s *Server) AddListeningIPAddr(addrStr string) error
  • func (s *Server) AddRelayIPAddr(addrStr string) error
  • func (s *Server) Close() error
  • func (s *Server) Start() error
• type ServerConfig

Types

type AuthHandler

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

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) Close

func (c *Client) Close()

Close closes this client

func (*Client) HandleInbound

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

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(relayedAddr net.Addr)

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

func (*Client) PerformTransaction

func (c *Client) PerformTransaction(msg *stun.Message, to net.Addr, dontWait 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 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

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

func NewSTUNConn(nextConn net.Conn) *STUNConn

NewSTUNConn creates a STUNConn

func (*STUNConn) Close

func (s *STUNConn) Close() error

Close implements Close from net.PacketConn

func (*STUNConn) LocalAddr

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

LocalAddr implements LocalAddr from net.PacketConn

func (*STUNConn) ReadFrom

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

ReadFrom implements ReadFrom from net.PacketConn

func (*STUNConn) SetDeadline

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

SetDeadline implements SetDeadline from net.PacketConn

func (*STUNConn) SetReadDeadline

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

SetReadDeadline implements SetReadDeadline from net.PacketConn

func (*STUNConn) SetWriteDeadline

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

SetWriteDeadline implements SetWriteDeadline from net.PacketConn

func (*STUNConn) WriteTo

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

WriteTo implements WriteTo from net.PacketConn

type Sender

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

func NewServer(config *ServerConfig) *Server

NewServer creates the Pion TURN server

func (*Server) AddExternalIPAddr

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: "185.199.108.153" Ex 2: "185.199.108.153/10.0.1.2" By default, no address mapping is used. This method must be called before calling Start().

func (*Server) AddListeningIPAddr

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

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

func (s *Server) Close() error

Close closes the connection.

func (*Server) Start

func (s *Server) Start() error

Start starts the server.

type ServerConfig

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.