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

License

MIT License - see LICENSE.md for full text

Documentation

Index

• func Create(args StartArguments) *server.Server
• func Start(args StartArguments)
• func StartClient(args ClientArguments) (interface{}, error)
• type Client
• type ClientArguments
• type Server
• type StartArguments

Functions

func Create

func Create(args StartArguments) *server.Server

Create creates the Pion TURN server, but does not call listen

func Start

func Start(args StartArguments)

Start the Pion TURN server

func StartClient

func StartClient(args ClientArguments) (interface{}, error)

StartClient starts a Pion client

Types

type Client

type Client interface {
	SendSTUNRequest(serverIP net.IP, serverPort int) (interface{}, error)
}

Client is the interface for Pion STUN requests

type ClientArguments

type ClientArguments struct {
	BindingAddress string
	ServerIP       net.IP
	ServerPort     int
}

ClientArguments are the arguments for the Pion client

type Server

type Server interface {
	AuthenticateRequest(username string, srcAddr net.Addr) (password string, ok bool)
}

Server is the interface for Pion TURN server callbacks

type StartArguments

type StartArguments struct {
	Server  Server
	Realm   string
	UDPPort int
}

StartArguments are the arguments for the Pion TURN server