esl/mongooseice

STUN/TURN server written in Elixir

MongooseICE

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.

mongooseice's Issues

not able to install : urgent

Hello all I have installed mongoseIM 2.0 successfully and using it now I need to implement audio/video call in my application, but installing the MongooseICE is too complex or there no such simple doc to get better knowledge.

Please help me in installing the MongooseICE, I am using ubuntu 16 on my server.

Thanks in advance

Support for releases in docker container

Building of the docker container for the project release should be easy and fun.

Support for EVEN-PORT attribute

allocate request requires support for EVEN-PORT attribute. The placeholder is in place, there is just need to the actual implementation and test.

Integrate metrics

Prior to running load tests the project should have some basic metrics available. This tasks consists of integrating a metrics system into the project and configuring some basic metrics like numer of relay packets processed and processing time of each TURN/STUN command.

Relay mechanism - data exchange between client and peers

This involves processing of Send indications from client and forwarding it to its peers through allocation socket, and receiving data on allocation socket and forwarding it to client via Data indications.

Documentation on usage and use cases

In a README, things that should be mentioned:

• Fennec is not a server, its servers
• how to start servers
• use cases (IoT, ..?)

Implement handling of allocate requests

This includes RFC-compliant responses to erroneous requests, authenticating and storing allocation metadata.

Do I need separate SIP system like routr.io to make VOIP work with MongooseIM

I am using MongooseIM with PostgreSQL as backend (for users). Now I want to add Voice calling (VOIP) support using MongooseIM and MongooseimICE. Following are the concerns:

1. Do I need to use a separate module like www.routr.io for SIP, or is it possible to do it with Mongooseim + MongooseimICE alone?
2. In the Mongooseim - jingle + routr.io tutorial, I can successfully create a voice call by following the tutorial. If I can do voice call with routr.io, then can I skip the MongooseimICE completely?

how to configure MongooseICE without docker

please help me with open detail of mongooseICE configuration on server i am using ubuntu 16.04 and postgres 9.5 databases for mongooseIM

Thanks for your support in advance

Guide for setting up for audio/video

Hi all.

When reading the Rationale for MongooseICE: "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."
That's fantastic. And I get so excited for being able to set up audio and video within the webapp my company is developing. We already have chat going with MongooseIM.

But then reality hits: for the life of me, I can't seem to find a comprehensive guide/tutorial/youtube/scribbled notes on a tissue/etc that takes me through the full setup to get two-way audio and video communication working. A master list of high level steps with links to other resources describing each high level step in detail is also perfectly acceptable.

Does such a guide exist?

Relay over channels

Same as #16 but over channels - processing of channel data messages from client and forwarding them to peers and vice versa.

inet_parse:~p:~p: erroneous line, skipped~n "/etc/resolv.conf"

I want to set up MongooseimICE on Raspberry PI with Raspbian OS.

I have build from the source code and it builds successfully.
$MIX_ENV=prod mix do deps.get, docker.build, docker.release

When I tried to run it with
$_build/prod/rel/mongooseice/bin/mongooseice console

it shows the below logs:

2019-04-03 07:33:02 inet_parse:~p:~p: erroneous line, SKIPPED~n
	"/etc/resolv.conf"
	3
Erlang/OTP 19 [erts-8.2.1] [source] [smp:4:4] [async-threads:10] [kernel-poll:false]


=INFO REPORT==== 3-Apr-2019::08:33:02 ===
inet_parse:"/etc/resolv.conf":3: erroneous line, SKIPPED

07:33:02.388 [info]  Starting STUN/TURN server (127.0.0.1:3478) with relay_ip: 127.0.0.1
Interactive Elixir (1.4.5) - press Ctrl+C to exit (type h() ENTER for help)
iex([email protected])1> 

Concerns:

1. What is the error inet_parse about and
2. Where to set general and UDP configuration?

My guess is error is due to config missing, please advice

Configuration of the release

Release of the application should be easy to configure (also in docker container)

How to set ice server in mongooseim.cfg

MongooseIM version 3.5.0
MongooseICE version 0.4.0
MongooseICE has been start with port 3478.
udp 0 0 127.0.0.1:3478 0.0.0.0:*

I found the ejabberd_stun options in mongoose.cfg,but I don't know how to set it.
%%,{ {3478, udp}, ejabberd_stun, []}

I try to find some tips in source code ,but souce code have no "ejabberd_stun" .

Can't start multiple UDP servers because of supervisor's children IDs conflict

When I try to start Fennec.UDP two times, I get an error that there is conflicting ID in top supervisor's children list. We assign different names to the servers, but we don't do that with children IDs, so supervisor rejects the second child.

authorization mechanism/ webrtc compatibility?

Just wondering is this using the same mechanism proposed in this slide?
https://www.ietf.org/proceedings/87/slides/slides-87-behave-10.pdf
(the stateless auth or the typical turn auth)

for some reason i can't get it to work trying to swap coturn with mongooseice (using stateless auth)

I also tried it using this demo to test the mongooseice
https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/

i left the username empty based on the guide here
https://mongooseim.readthedocs.io/en/latest/user-guide/ICE_tutorial/
but not sure what to do with how to set the realm using webrtc protocol

Support for distillery releases

It should be possible to build a distillery release for the application.

Document supported STUN/TURN methods and attributes

Environment Values are ignored when built as "dev", but are picked up properly in "prod"

My environment variables:

Name                           Value
----                           -----
MONGOOSEICE_UDP_BIND_IP        0.0.0.0
MONGOOSEICE_UDP_PORT           3478
MONGOOSEICE_LOGLEVEL           debug
MIX_ENV                        dev

cleaned and built, I see this:

D:\repos\MongooseICE [master ≡ +2 ~1 -0 !]> mix clean
D:\repos\MongooseICE [master ≡ +2 ~1 -0 !]> iex.bat -S mix
Compiling 29 files (.ex)
Generated mongooseice app

14:49:41.138 [info]  Starting STUN/TURN server (127.0.0.1:12100) with relay_ip: 127.0.0.1

14:49:41.144 [info]  Starting STUN/TURN server (127.0.0.1:12200) with relay_ip: 127.0.0.1
Interactive Elixir (1.5.2) - press Ctrl+C to exit (type h() ENTER for help)

switched to prod:

Name                           Value
----                           -----
MONGOOSEICE_UDP_BIND_IP        0.0.0.0
MONGOOSEICE_UDP_PORT           3478
MONGOOSEICE_LOGLEVEL           debug
MIX_ENV                        prod

D:\repos\MongooseICE [master ≡ +2 ~1 -0 !]> mix clean
D:\repos\MongooseICE [master ≡ +2 ~1 -0 !]> iex.bat -S mix
Compiling 29 files (.ex)
Generated mongooseice app

14:50:47.222 [info]  Starting STUN/TURN server (0.0.0.0:3478) with relay_ip: 127.0.0.1
Interactive Elixir (1.5.2) - press Ctrl+C to exit (type h() ENTER for help)

Other oddities:

• The port used when I start it in "dev" isn't documented as the default port
• in "dev" I see the Starting Stun/Turn server twice
• despite the MONGOOSEICE_LOGLEVEL set to debug, I never see any messages other than [info]

Here's the commit I'm building off of:

D:\repos\MongooseICE [master ≡ +2 ~1 -0 !]> git show -s
commit 4c2792b2e01ccff377c8f78b131a5ca2b064f39b
Author: Arkadiusz Gil <[email protected]>
Date:   Mon Sep 25 14:30:25 2017 +0200

    Include logo and homepage in the docs

Support for RESERVATION-TOKEN attribute

allocate request requires support for RESERVATION-TOKEN attribute. The placeholder is in place, there is just need to the actual implementation and test.

Handling CreatePermission requests

In order to allow its peer to use allocation, client must send CreatePermission request to a server which installs permission for specific time.

This also includes timeouts of permissions and extending their lifetime on valid requests.

Support for DONT-FRAGMENT attribute

allocate request requires support for DONT-FRAGMENT attribute. The placeholder is in place, there is just need to the actual implementation and test.

There may be some issues with the implementation. Probably, the only way of setting this flag on the socket in Erlang is to set raw socket option which requires not only knowledge of the platform, code is running on but also the flag values from system headers. Implementing this feature may result in very messy and hacky code.

Relay UDP socket: {:active, true} is not an option for a production system

See lib/fennec/evaluator/allocate/request.ex and search for :gen_udp.open.

It's not an option for a production system due to the risk of uncontrolled process message queue flooding by the peers. Especially in this case, since the single process in Fennec corresponds to multiple TURN peers.

Handling Refresh requests

This includes implementing expiration of allocations and extending expiration time on valid Refresh requests.

MongooseICE with ejabberd

Hi
I am using ejabberd now I wanted to integrate the MongooseICE in it , can any one please help me how I can achieve that.

Start servers with configuration

We should allow users to start servers via their project configuration (should be pretty simple to implement using Fennec.UDP.start

For example:

config :fennec, :servers,
  udp: [ip: {127, 0, 0, 1}, port: 3478]

This should start a UDP server on Fennec's start.

Sign responses with MESSAGE-INTEGRITY

Currently Fennec does not sign responses with MESSAGE-INTEGRITY. TURN clients do not require messages to be signed, but if they are, MESSAGE-INTEGRITY must be checked. It's just an extra security measure.

Processing ChannelBind requests

This includes validation of requests and storing channels metadata in the worker process.