turn

package module
v1.3.7-0...-4388ba3 Latest Latest
Warning

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

 Go to latest Published: Nov 13, 2019 License: MIT Imports: 19 Imported by: 0

README

Pion TURN
Pion TURN

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

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

Planned

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:

License

MIT License - see LICENSE.md for full text

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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 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.

Source Files

View all Source files

Directories

Path Synopsis
examples
turn-client
turn-server
internal
allocation
client
ipnet
proto
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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.