MongooseICE
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 oneMONGOOSEICE_UDP_ENABLED
-true
/false
- Enable or disable UDP STUN/TURN interface. Enabled by defaultMONGOOSEICE_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 is127.0.0.1
, but in case of docker container the default is0.0.0.0
MONGOOSEICE_UDP_PORT
- Port which server listens on for STUN/TURN requests. Default is3478
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. Allallocate
requests will return this IP address to the client, therefore this cannot be set to0.0.0.0
. Release default is127.0.0.1
, but in case of docker container the default is set to the first IP address returned byhostname -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.