Statistics
| Branch: | Revision:

janus-gateway / README.md @ 85f421cf

History | View | Annotate | Download (18.1 KB)

1
Janus WebRTC Gateway
2
====================
3

    
4
Janus is an open source, general purpose, WebRTC gateway designed and
5
developed by [Meetecho](http://www.meetecho.com). This version
6
of the gateway can only be installed on Linux systems: next versions
7
will take into account cross compilation on different environments.
8

    
9
For some online demos and documentations, make sure you pay the
10
[project website](http://janus.conf.meetecho.com/) a visit!
11

    
12
To discuss Janus with us and other users, there's a Google Group called
13
[meetecho-janus](http://groups.google.com/d/forum/meetecho-janus) that
14
you can use. If you encounter issues, though, please submit an issue
15
on [github](https://github.com/meetecho/janus-gateway/issues) instead.
16

    
17

    
18
## Dependencies
19
To install it, you'll need to satisfy the following dependencies:
20

    
21
* [Jansson](http://www.digip.org/jansson/)
22
* [libnice](http://nice.freedesktop.org/wiki/)
23
* [OpenSSL](http://www.openssl.org/) (at least v1.0.1e)
24
* [libsrtp](https://github.com/cisco/libsrtp) (at least v1.5 suggested)
25
* [usrsctp](https://github.com/sctplab/usrsctp) (only needed if you
26
are interested in Data Channels)
27
* [libmicrohttpd](http://www.gnu.org/software/libmicrohttpd/) (only
28
needed if you are interested in REST support for the Janus API)
29
* [libwebsockets](https://libwebsockets.org/) (only needed if
30
you are interested in WebSockets support for the Janus API)
31
* [cmake](http://www.cmake.org/) (only needed if you are interested in
32
WebSockets and/or BoringSSL support, as they make use of it)
33
* [rabbitmq-c](https://github.com/alanxz/rabbitmq-c) (only needed if
34
you are interested in RabbitMQ support for the Janus API)
35
* [paho.mqtt.c](https://eclipse.org/paho/clients/c) (only needed if
36
you are interested in MQTT support for the Janus API)
37
* [libcurl](https://curl.haxx.se/libcurl/) (only needed if you are
38
interested in the TURN REST API support)
39

    
40
A couple of plugins depend on a few more libraries:
41

    
42
* [Sofia-SIP](http://sofia-sip.sourceforge.net/) (only needed for the SIP plugin)
43
* [libopus](http://opus-codec.org/) (only needed for the bridge plugin)
44
* [libogg](http://xiph.org/ogg/) (only needed for the voicemail plugin)
45
* [libcurl](https://curl.haxx.se/libcurl/) (only needed if you are
46
interested in RTSP support in the Streaming plugin or in the sample
47
Event Handler plugin)
48

    
49
Additionally, you'll need the following libraries and tools:
50

    
51
* [GLib](http://library.gnome.org/devel/glib/)
52
* [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/)
53
* [gengetopt](http://www.gnu.org/software/gengetopt/)
54

    
55
All of those libraries are usually available on most of the most common
56
distributions. Installing these libraries on a recent Fedora, for
57
instance, is very simple:
58

    
59
    yum install libmicrohttpd-devel jansson-devel libnice-devel \
60
       openssl-devel libsrtp-devel sofia-sip-devel glib-devel \
61
       opus-devel libogg-devel libcurl-devel pkgconfig gengetopt \
62
       libtool autoconf automake
63

    
64
Notice that you may have to `yum install epel-release` as well if you're
65
attempting an installation on a CentOS machine instead.
66

    
67
On Ubuntu or Debian, it would require something like this:
68

    
69
	aptitude install libmicrohttpd-dev libjansson-dev libnice-dev \
70
		libssl-dev libsrtp-dev libsofia-sip-ua-dev libglib2.0-dev \
71
		libopus-dev libogg-dev libcurl4-openssl-dev pkg-config gengetopt \
72
		libtool automake
73

    
74
* *Note:* please notice that libopus may not be available out of the box
75
on Ubuntu or Debian, unless you're using a recent version (e.g., Ubuntu
76
14.04 LTS). In that case, you'll have to [install it manually](http://www.opus-codec.org).
77

    
78
* *Note:* For custom installations of libnice, you can run
79
`pkg-config --cflags --libs nice` to make sure Janus can find the
80
installation. If not, you may need to set the `PKG_CONFIG_PATH`
81
environment variable prior to compiling Janus, eg.
82
`export PKG_CONFIG_PATH=/path/to/libnice/lib/pkgconfig`
83

    
84
In case you're interested in compiling the sample Event Handler plugin,
85
you'll need to install the development version of libcurl as well (usually
86
`libcurl-devel` on Fedora/CentOS, `libcurl4-openssl-dev` on Ubuntu/Debian).
87

    
88
If your distro ships a pre-1.5 version of libsrtp, you'll have to
89
uninstall that version and [install 1.5 or 2.0.0 manually](https://github.com/cisco/libsrtp/releases).
90
In fact, 1.4.x is known to cause several issues with WebRTC. Installation
91
of version 1.5.4 is quite straightforward:
92

    
93
	wget https://github.com/cisco/libsrtp/archive/v1.5.4.tar.gz
94
	tar xfv v1.5.4.tar.gz
95
	cd libsrtp-1.5.4
96
	./configure --prefix=/usr --enable-openssl
97
	make shared_library && sudo make install
98

    
99
The instructions for version 2.0.0 is practically the same:
100

    
101
	wget https://github.com/cisco/libsrtp/archive/v2.0.0.tar.gz
102
	tar xfv v2.0.0.tar.gz
103
	cd libsrtp-2.0.0
104
	./configure --prefix=/usr --enable-openssl
105
	make shared_library && sudo make install
106

    
107
The Janus configure script autodetects which one you have installed and
108
links to the correct library automatically, choosing v2.0.0 if both are
109
installed. If you want v1.5.4 to be picked, pass `--disable-libsrtp2`
110
when configuring Janus to force it to use the older version instead.
111

    
112
* *Note:* when installing libsrtp, no matter which version, you may need to pass
113
`--libdir=/usr/lib64` to the configure script if you're installing on a x86_64 distribution.
114

    
115
If you want to make use of BoringSSL instead of OpenSSL (e.g., because
116
you want to take advantage of `--enable-dtls-settimeout`), you'll have
117
to manually install it to a specific location. Use the following steps:
118

    
119
	git clone https://boringssl.googlesource.com/boringssl
120
	cd boringssl
121
	# Don't barf on errors
122
	sed -i s/" -Werror"//g CMakeLists.txt
123
	# Build
124
	mkdir -p build
125
	cd build
126
	cmake -DCMAKE_CXX_FLAGS="-lrt" ..
127
	make
128
	cd ..
129
	# Install
130
	sudo mkdir -p /opt/boringssl
131
	sudo cp -R include /opt/boringssl/
132
	sudo mkdir -p /opt/boringssl/lib
133
	sudo cp build/ssl/libssl.a /opt/boringssl/lib/
134
	sudo cp build/crypto/libcrypto.a /opt/boringssl/lib/
135

    
136
Once the library is installed, you'll have to pass an additional
137
`--enable-boringssl` flag to the configure script, as by default
138
Janus will be built assuming OpenSSL will be used. By default, Janus
139
expects BoringSSL to be installed in `/opt/boringssl` -- if it's
140
installed in another location, pass the path to the configure script
141
as such: `--enable-boringssl=/path/to/boringssl` If you were using
142
OpenSSL and want to switch to BoringSSL, make sure you also do a
143
`make clean` in the Janus folder before compiling with the new
144
BoringSSL support. If you enabled BoringSSL support and also want Janus
145
to detect and react to DTLS timeouts with faster retransmissions, then
146
pass `--enable-dtls-settimeout` to the configure script too.
147

    
148
For what concerns usrsctp, which is needed for Data Channels support, it
149
is usually not available in repositories, so if you're interested in
150
them (support is optional) you'll have to install it manually. It is a
151
pretty easy and standard process:
152

    
153
	git clone https://github.com/sctplab/usrsctp
154
	cd usrsctp
155
	./bootstrap
156
	./configure --prefix=/usr && make && sudo make install
157

    
158
* *Note:* you may need to pass `--libdir=/usr/lib64` to the configure
159
script if you're installing on a x86_64 distribution.
160

    
161
The same applies for libwebsockets, which is needed for the optional
162
WebSockets support. If you're interested in supporting WebSockets to
163
control Janus, as an alternative (or replacement) to the default plain
164
HTTP REST API, you'll have to install it manually:
165

    
166
	git clone git://git.libwebsockets.org/libwebsockets
167
	cd libwebsockets
168
	# If you want the stable version of libwebsockets, uncomment the next line
169
	# git checkout v1.5-chrome47-firefox41
170
	mkdir build
171
	cd build
172
	# See https://github.com/meetecho/janus-gateway/issues/732 re: LWS_MAX_SMP
173
	cmake -DLWS_MAX_SMP=1 -DCMAKE_INSTALL_PREFIX:PATH=/usr -DCMAKE_C_FLAGS="-fpic" ..
174
	make && sudo make install
175

    
176
* *Note:* if libwebsockets.org is unreachable for any reason, replace
177
the first line with this:
178

    
179
	git clone https://github.com/warmcat/libwebsockets.git
180

    
181
The same applies for Eclipse Paho MQTT C client library, which is needed
182
for the optional MQTT support. If you're interested in integrating MQTT
183
queues as an alternative (or replacement) to HTTP and/or WebSockets
184
to control Janus, you can install the latest version with the
185
following steps:
186

    
187
	git clone https://github.com/eclipse/paho.mqtt.c.git
188
	cd paho.mqtt.c
189
	make && sudo make install
190

    
191
* *Note:* you may want to set up a different install path for the library,
192
to achieve that, replace the last command by 'sudo prefix=/usr make install'.
193

    
194
Finally, the same can be said for rabbitmq-c as well, which is needed
195
for the optional RabbitMQ support. In fact, several different versions
196
of the library can be found, and the versions usually available in most
197
distribution repositories are not up-do-date with respect to the current
198
state of the development. As such, if you're interested in integrating
199
RabbitMQ queues as an alternative (or replacement) to HTTP and/or
200
WebSockets to control Janus, you can install the latest version with the
201
following steps:
202

    
203
	git clone https://github.com/alanxz/rabbitmq-c
204
	cd rabbitmq-c
205
	git submodule init
206
	git submodule update
207
	mkdir build && cd build
208
	cmake -DCMAKE_INSTALL_PREFIX=/usr ..
209
	make && sudo make install
210

    
211
* *Note:* you may need to pass `--libdir=/usr/lib64` to the configure
212
script if you're installing on a x86_64 distribution.
213

    
214
To conclude, should you be interested in building the gateway
215
documentation as well, you'll need some additional tools too:
216

    
217
* [Doxygen](http://www.doxygen.org)
218
* [Graphviz](http://www.graphviz.org/)
219

    
220
On Fedora:
221

    
222
	yum install doxygen graphviz
223

    
224
On Ubuntu/Debian:
225

    
226
	aptitude install doxygen graphviz
227

    
228

    
229
## Compile
230
Once you have installed all the dependencies, get the code:
231

    
232
	git clone https://github.com/meetecho/janus-gateway.git
233
	cd janus-gateway
234

    
235
Then just use:
236

    
237
	sh autogen.sh
238

    
239
to generate the configure file. After that, configure and compile as
240
usual to start the whole compilation process:
241

    
242
	./configure --prefix=/opt/janus
243
	make
244
	make install
245

    
246
Since Janus requires configuration files for both the core and its
247
modules in order to work, you'll probably also want to install the
248
default configuration files to use, which you can do this way:
249

    
250
	make configs
251

    
252
Remember to only do this once, or otherwise a subsequent `make configs`
253
will overwrite any configuration file you may have modified in the
254
meanwhile.
255

    
256
If you're installed the above libraries but are not interested in Data
257
Channels, WebSockets, MQTT and/or RabbitMQ (or you don't care about any
258
of them), you can disable them when configuring:
259

    
260
	./configure --disable-websockets --disable-data-channels --disable-rabbitmq --disable-mqtt
261

    
262
If the libraries are not installed, instead, no need to manually disable
263
them, as the configure script will skip them automatically and disable
264
the related features by itself. A summary of what's going to be built
265
will always appear after you do a configure, allowing you to double
266
check if what you need and don't need is there.
267

    
268
If Doxygen and graphviz are available, the process can also build the
269
documentation for you. By default the compilation process will not try
270
to build the documentation, so if you instead prefer to build it, use the
271
--enable-docs configuration option:
272

    
273
	./configure --enable-docs
274

    
275
You can also selectively enable/disable other features (e.g., specific
276
plugins you don't care about, or whether or not you want to build the
277
recordings post-processor). Use the --help option when configuring
278
for more info.
279

    
280

    
281
### Building on MacOS
282
While most of the above instructions will work when compiling Janus on
283
MacOS as well, there are a few aspects to highlight when doing that.
284

    
285
First of all, you can use `brew` to install most of the dependencies:
286

    
287
	brew tap homebrew/boneyard
288
	brew install jansson libnice openssl libusrsctp libmicrohttpd libwebsockets cmake rabbitmq-c sofia-sip opus libogg libcurl glib pkg-config gengetopt autoconf automake libtool
289

    
290
For what concerns `libsrtp`, which needs to be installed manually, just
291
pass `/usr/local` as a prefix when configuring, and proceed as normal:
292

    
293
	[..]
294
	./configure --prefix=/usr/local
295
	[..]
296

    
297
Finally, you may need to provide a custom `prefix` and `PKG_CONFIG_PATH`
298
when configuring Janus as well:
299

    
300
	./configure --prefix=/usr/local/janus PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig
301

    
302
Everything else works exactly the same way as on Linux.
303

    
304
## Configure and start
305
To start the gateway, you can use the janus executable. There are several
306
things you can configure, either in a configuration file:
307

    
308
	<installdir>/etc/janus/janus.cfg
309

    
310
or on the command line:
311

    
312
	<installdir>/bin/janus --help
313

    
314
	janus 0.2.6
315

    
316
	Usage: janus [OPTIONS]...
317

    
318
	-h, --help                    Print help and exit
319
	-V, --version                 Print version and exit
320
	-b, --daemon                  Launch Janus in background as a daemon
321
                                  (default=off)
322
	-N, --disable-stdout          Disable stdout based logging  (default=off)
323
	-L, --log-file=path           Log to the specified file (default=stdout only)
324
	-i, --interface=ipaddress     Interface to use (will be the public IP)
325
	-P, --plugins-folder=path     Plugins folder (default=./plugins)
326
	-C, --config=filename         Configuration file to use
327
	-F, --configs-folder=path     Configuration files folder (default=./conf)
328
	-c, --cert-pem=filename       DTLS certificate
329
	-k, --cert-key=filename       DTLS certificate key
330
	-S, --stun-server=filename    STUN server(:port) to use, if needed (e.g.,
331
								  gateway behind NAT, default=none)
332
	-1, --nat-1-1=ip              Public IP to put in all host candidates,
333
                                  assuming a 1:1 NAT is in place (e.g., Amazon
334
                                  EC2 instances, default=none)
335
	-E, --ice-enforce-list=list   Comma-separated list of the only interfaces to
336
                                  use for ICE gathering; partial strings are
337
                                  supported (e.g., eth0 or eno1,wlan0,
338
                                  default=none)
339
	-X, --ice-ignore-list=list    Comma-separated list of interfaces or IP
340
                                  addresses to ignore for ICE gathering;
341
                                  partial strings are supported (e.g.,
342
                                  vmnet8,192.168.0.1,10.0.0.1 or
343
                                  vmnet,192.168., default=vmnet)
344
	-6, --ipv6-candidates         Whether to enable IPv6 candidates or not
345
                                  (experimental)  (default=off)
346
	-l, --libnice-debug           Whether to enable libnice debugging or not
347
                                  (default=off)
348
	-I, --ice-lite                Whether to enable the ICE Lite mode or not
349
                                  (default=off)
350
	-T, --ice-tcp                 Whether to enable ICE-TCP or not (warning: only
351
                                  works with ICE Lite)
352
                                  (default=off)
353
	-U, --bundle                  Whether to force BUNDLE or not (whether audio,
354
                                  video and data will always be bundled)
355
                                  (default=off)
356
	-u, --rtcp-mux                Whether to force rtcp-mux or not (whether RTP
357
                                  and RTCP will always be muxed)  (default=off)
358
	-q, --max-nack-queue=number   Maximum size of the NACK queue (in ms) per user
359
                                  for retransmissions
360
	-t, --no-media-timer=number   Time (in s) that should pass with no media
361
                                  (audio or video) being received before Janus
362
                                  notifies you about this
363
	-r, --rtp-port-range=min-max  Port range to use for RTP/RTCP (only available
364
								  if the installed libnice supports it)
365
	-d, --debug-level=1-7         Debug/logging level (0=disable debugging,
366
                                  7=maximum debug level; default=4)
367
	-D, --debug-timestamps        Enable debug/logging timestamps  (default=off)
368
	-o, --disable-colors          Disable color in the logging  (default=off)
369
	-a, --apisecret=randomstring  API secret all requests need to pass in order
370
                                  to be accepted by Janus (useful when wrapping
371
                                  Janus API requests in a server, none by
372
                                  default)
373
	-A, --token-auth              Enable token-based authentication for all
374
                                  requests  (default=off)
375
	-e, --event-handlers          Enable event handlers  (default=off)
376

    
377
Options passed through the command line have the precedence on those
378
specified in the configuration file. To start the gateway, simply run:
379

    
380
	<installdir>/bin/janus
381

    
382
This will start the gateway, and have it look at the configuration file.
383

    
384
As far as transports are concerned (that is, with respect to how you can
385
interact with your Janus instance), using the default configuration files
386
provided after issuing a `make configs` will result in Janus only
387
enabling an HTTP webserver (port 8088) and a plain WebSocket server (8188),
388
assuming the related transport modules have been compiled, of course.
389
To enable HTTPS or Secure WebSockets support, edit the related transport
390
configuration file accordingly. You can also change the base path that
391
the webserver uses: by default this is `/janus`, but you can change
392
it to anything you want and with any nesting you want (e.g., `/mypath`,
393
`/my/path`, or `/my/really/nested/path`). This is done to allow
394
you to more easily customize rules in any frontend you may have (e.g.,
395
Apache in front of your services). Please notice that the path configuration
396
is not provided for WebSockets, instead, as it is not needed there. The
397
RabbitMQ module, if compiled, is disabled by default, so you'll have
398
to enable it manually if interested in it.
399

    
400
To test whether it's working correctly, you can use the demos provided
401
with this package in the `html` folder: these are exactly the same demos
402
available online on the [project website](http://janus.conf.meetecho.com/).
403
Just copy the file it contains in a webserver, or use a userspace webserver
404
to serve the files in the `html` folder (e.g., with php or python),
405
and open the index.html page in either Chrome or Firefox. A list of demo
406
pages exploiting the different plugins will be available. Remember to
407
edit the transport/port details in the demo JavaScript files if you
408
changed any transport-related configuration from its defaults.
409

    
410

    
411
## Help us!
412
Any thought, feedback or (hopefully not!) insult is welcome!
413

    
414
Developed by [@meetecho](https://github.com/meetecho)