• Stars
    star
    118
  • Rank 299,866 (Top 6 %)
  • Language
    Elixir
  • License
    Other
  • Created almost 8 years ago
  • Updated about 5 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

STUN/TURN server written in Elixir

MongooseICE

Build Status Coverage Status

Documentation

MongooseICE is a STUN server by Erlang Solutions whose internals aim to be well written and tested.

Rationale

Many modern applications (mobile and web) are media intensive like those involving audio, video, gaming, and file transfer. MongooseICE helps to get communication done peer-to-peer (without going through a server) so your bandwidth and server-side costs don't need to be as much of a concern.

Resources

Some helpful technical material:

  • For the bigger picture see the RTCPeerConnection plus servers section under this tutorial
  • MongooseICE alone isn't enough to get peer-to-peer communication going. The reason why is described in this tutorial. Our XMPP server, MongooseIM, is perfect for building a combination of signaling and chat applications
  • Find the STUN, TURN, and ICE RFCs (at the IETF site)

Installation as part of other application

MongooseICE is available on Hex. To use it, just add it to your dependencies:

def deps do
  [
    {:mongooseice, "~> 0.4.0"}
  ]
end

Installation as standalone service

For now there are two ways of starting MongooseICE as standalone application. Via release built from source or via prebuilt docker image. The docker image could be used for production system with a proper network setup (the easiest one would be --net=host docker option). For developement on non-docker-native platforms it is probably easier to start the built release then setup docker container to work correctly. This is due to the fact that TURN server uses system ephemeral port pool for allocations, which is not so easy to map to the host machine. This issue is not visible on Linux systems, since you can allow docker to use its private virtual network and just use the docker container's IP address as the relay IP (which is set this way in MongooseICE by default when using the docker image).

Building and using a release

You may build the release and use it on production system. In order to do that, just type:

MIX_ENV=prod mix do deps.get, release

The release can be configured by environment variables described in Configuration section below.

Using docker prebuilt container

You can use our prebuilt docker images on our dockerhub:

docker run -it -p 3478:3478/udp -e "MONGOOSEICE_STUN_SECRET=very_secret" mongooseim/mongooseice

This command will start the MongooseICE server with default configuration and with STUN secret set to very_secret. If you are using this on Linux, the part with -p 3478:3478/udp is not needed, since you can access the server directly using the container's IP. You can configure the server by passing environment variables to the container. All those variables are described in Configuration section below.

Building docker container

Well, that's gonna be quite simple and short:

MIX_ENV=prod mix do deps.get, docker.build, docker.release

And that's it. You have just built MongooseICE's docker image. The name of the image should be visible at the end of the output of the command you've just run. You can configure the container by setting environment variables that are described in Configuration section below.

Configuration

Assuming you are using release built with env prod or the docker image, you will have access to the following system's environment viaribles:

General configuration
  • MONGOOSEICE_LOGLEVEL - debug/info/warn/error - Log level of the application. info is the default one
  • MONGOOSEICE_UDP_ENABLED - true/false - Enable or disable UDP STUN/TURN interface. Enabled by default
  • MONGOOSEICE_TCP_ENABLED - true/false - Not yet supported - Enable or disable TCP STUN/TURN interface. Disabled by default.
  • MONGOOSEICE_STUN_SECRET - Secret that STUN/TURN clients have to use to authorize with the server
UDP configuration

The following variables configure UDP STUN/TURN interface. It must be enabled via MONGOOSEICE_UDP_ENABLED=true in order for those options to take effect.

  • MONGOOSEICE_UDP_BIND_IP - IP address on which MongooseICE listens for requests. Release default is 127.0.0.1, but in case of docker container the default is 0.0.0.0
  • MONGOOSEICE_UDP_PORT - Port which server listens on for STUN/TURN requests. Default is 3478
  • MONGOOSEICE_UDP_REALM - Realm name for this MongooseICE server as defined in TURN RFC. Default: udp.localhost.local
  • MONGOOSEICE_UDP_RELAY_IP - IP of the relay interface. All allocate requests will return this IP address to the client, therefore this cannot be set to 0.0.0.0. Release default is 127.0.0.1, but in case of docker container the default is set to the first IP address returned by hostname -i on the container.
TCP configuration

TCP is not yet supported.

Checklist of STUN/TURN methods supported by MongooseICE

  • Binding
  • Allocate
  • Refresh
  • Send
  • Data
  • CreatePermission
  • ChannelBind

Checklist of STUN/TURN attributes supported by MongooseICE

Comprehension Required

  • XOR-MAPPED-ADDRESS
  • MESSAGE-INTEGRITY
  • ERROR-CODE
  • UNKNOWN-ATTRIBUTES
  • REALM
  • NONCE
  • CHANNEL-NUMBER
  • LIFETIME
  • XOR-PEER-ADDRESS
  • DATA
  • XOR-RELAYED-ADDRESS
  • EVEN-PORT
  • REQUESTED-TRANSPORT
  • DONT-FRAGMENT
  • RESERVATION-TOKEN
  • PRIORITY
  • USE-CANDIDATE
  • ICE-CONTROLLED
  • ICE-CONTROLLING

Comprehension Optional

  • SOFTWARE
  • ALTERNATE-SERVER
  • FINGERPRINT

License

Copyright 2017 Erlang Solutions Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

More Repositories

1

MongooseIM

MongooseIM is Erlang Solutions' robust, scalable and efficient XMPP server, aimed at large installations. Specifically designed for enterprise purposes, it is fault-tolerant and can utilise the resources of multiple clustered machines.
Erlang
1,660
star
2

gradient

Gradient is a static typechecker for Elixir
Elixir
431
star
3

erlang-handbook

A concise reference for Erlang
TeX
296
star
4

erlang_ale

Erlang Actor Library for Embedded -- An embedded framework from Erlang Solutions
C
208
star
5

escalus

An XMPP client library in Erlang for conveniently testing XMPP servers
Erlang
127
star
6

lhttpc

lhttpc is a lightweight HTTP/1.1 client implemented in Erlang.
Erlang
127
star
7

MongoosePush

MongoosePush is a simple Elixir RESTful service allowing to send push notification via FCM and/or APNS.
Elixir
108
star
8

elarm

Erlang
102
star
9

amoc

A load-testing framework for running massively parallel tests
Erlang
96
star
10

ex_rabbit_pool

RabbitMQ connection pooling in Elixir
Elixir
73
star
11

erlang-web

Erlang
50
star
12

parcv

Computer vision demo running on the parallella board
C
38
star
13

mangosta-android

MongooseIM client for Android
Java
31
star
14

mangosta-ios

MongooseIM client for iOS
Swift
30
star
15

sparrow

iOS and Android push notifications for Elixir.
Elixir
30
star
16

mongooseim-docker

Shell
27
star
17

segmented_cache

Modern, performant, and extensible, Erlang in-memory cache
Erlang
27
star
18

ex_docker_build

docker build with support for bind mounts at build time via Docker Remote API
Elixir
25
star
19

ejabberd_tests

Erlang
23
star
20

flex

A simple Elixir InfluxDB client.
Elixir
20
star
21

erl_fuzzy_match

Erlang Fuzzy String Matcher
Erlang
18
star
22

lager_graylog

Lager is a standard logging tool for Erlang, this project crates lager formatter to output messages in gelf format and lager backend to send messages via UDP.
Erlang
17
star
23

arnold

Time series data forecasting tool made in Elixir using Axon library
Elixir
17
star
24

fast_scram

Fastest SCRAM's implementation for Erlang & OTP, aiming at performance and statelessness for ease-of-use
Erlang
17
star
25

tracerl

Dynamic tracing tests and utilities for Erlang/OTP
Erlang
17
star
26

cets

A library to synchronise records from the ETS tables between nodes
Erlang
15
star
27

jerboa

STUN/TURN encoder, decoder and client library in Elixir
Elixir
14
star
28

MongooseHelm

Helm chart definitions for the Mongoose stack (MongooseIM, MongoosePush)
Erlang
11
star
29

rebar3_codecov

A rebar3 plugin which converts .coverdata files to JSON format, compatible with
Erlang
11
star
30

elibcloud

Erlang wrapper for Libcloud
Erlang
10
star
31

packages

Makefile- and Docker-based build system for ESL's erlang and elixir binary packages.
Python
9
star
32

fast_pbkdf2

Erlang's best pbkdf2 implementation
C
9
star
33

rabbitmq-docker

Dockerfile
8
star
34

usec

Convert anything to microseconds and back.
Erlang
8
star
35

c3card

A workshop at CodeBEAM America 2024 showcasing custom hardware and Erlang-based firmware development using AtomVM.
Erlang
8
star
36

esl-rabbitmq-client

RabbitMQ Client for Erlang, built by ESL
Erlang
7
star
37

amoc-arsenal-xmpp

Erlang
7
star
38

erlang-osx-installer

Erlang Installer & Auto-Updater for macOS
Swift
6
star
39

buildex_api

Elixir
6
star
40

mongoose_jid

Erlang
5
star
41

movim-docker

Dockerfiles for movim application
Shell
5
star
42

jaguar

Elixir
5
star
43

wombat_discovery

Erlang
5
star
44

logger_graylog_backend

Elixir's Logger backend for Graylog
Elixir
5
star
45

opuntia

Opuntia is a basic set of tools for traffic shaping for erlang and elixir. Because if you touch it too fast, it stings you.
Erlang
5
star
46

gradient_macros

Slim Gradient compile-time support
Elixir
4
star
47

chirp_cockroach

Demo project: Chris McCord's Twitter clone with a CockroachDB backend
Elixir
4
star
48

buildex_jobs

Buildex service which receives and processes build instructions
Elixir
4
star
49

throttle

Experimental implementation of a simple throttle
Erlang
4
star
50

wombat-discovery

Plugin for Wombat to automatically add nodes
Elixir
4
star
51

buildex_poller

Buildex service which polls github (others to follow) and triggers builds via RabbitMQ
Elixir
4
star
52

release_poller

Elixir
4
star
53

base16

The last time I hexadecimify Erlang binaries...
Erlang
4
star
54

poc_tensorflow_mushrooms

Elixir
3
star
55

beam_olympics_nerves

Getting Beam Olympics to run on a Raspberry Pi through Nerves. Phoenix leaderboard included.
Erlang
3
star
56

erlang-plts

Pregenerated Dialyzer PLTs for a number of Erlang versions
Python
3
star
57

exometer_report_statsd

Erlang
3
star
58

seta

Work-stealing scheduler
JavaScript
3
star
59

ice_demo

Elixir
3
star
60

loadex

simple small open load generator
Elixir
2
star
61

MongooseDocs

Documentation for MongooseIM, in this repo's gh-pages: https://esl.github.io/MongooseDocs/latest/
HTML
2
star
62

buildex_ui

Buildex service which provides Oauth login and build configuration management
2
star
63

rabbitmq-queue-info

Makefile
2
star
64

gapp

Erlang
2
star
65

ex_github_poller

An elixir application to poll github repositories ... wip
Elixir
2
star
66

helm-chart

Shell
2
star
67

elarm_mailer

SMTP reporting for elarm
Erlang
2
star
68

Mercutio

Erlang
2
star
69

percacdat

Persistent Cached Data structures
Erlang
2
star
70

elixirconf-eu-jekyll

HTML
2
star
71

ice

Erlang
2
star
72

jekyll-codesync-global

jekyll version of codesync-global
SCSS
2
star
73

buildex_common

Modules shared by buildex projects
Elixir
2
star
74

cfg

Erlang
2
star
75

foo-phx-cowboy-2.6

phoenix 1.4 / cowboy-2.6 bootstrap project
Elixir
2
star
76

exometer_report_graphite

Erlang
2
star
77

mongooseim-ct-reports

Autogenerated repository for Common Tests reports. Used by MongooseIM team
JavaScript
2
star
78

bryan_cb_sf_2020_talk

bryan hunt codebeam talk
Makefile
2
star
79

amoc-swarm

Dockerfile
2
star
80

node-with-build-tools

node with build tools pre-installed
Dockerfile
2
star
81

release_tasks

Elixir
2
star
82

graphql-erlang

Erlang
2
star
83

amoc_rest

The generated server code for AMOC REST API
Erlang
2
star
84

elixometer

Elixir
2
star
85

observability

Examples for the Erlang and Elixir Observability tutorial
Erlang
1
star
86

jekyll-codesync-global-2

CSS
1
star
87

erlangusergroup

1
star
88

circleci-mim-results

JavaScript
1
star
89

sappan

Erlang
1
star
90

virtual-elixirconf-eu-jekyll

HTML
1
star
91

tanka-alpine

devops docker image with tanka, jsonnet, and jsonnet-package pre-installed
Dockerfile
1
star
92

ml-hackathon

Python
1
star
93

circleci-kubernetes-deployer

docker image with helm, kubectl, google cloud tools, etc baked in
Dockerfile
1
star
94

code-beam-america

HTML
1
star
95

plantproxy

Elixir
1
star
96

lambdadays-jekyll

convert lambdadays from custom webserver to jekyll
HTML
1
star