Statistics
| Branch: | Revision:

janus-gateway / README.md @ f82a8605

History | View | Annotate | Download (13.4 KB)

1 be35facb meetecho
Janus WebRTC Gateway
2
====================
3
4 39cdaef0 meetecho
Janus is an open source, general purpose, WebRTC gateway designed and
5
developed by [Meetecho](http://www.meetecho.com). This version
6 be35facb meetecho
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 70305f47 meetecho
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 be35facb meetecho
##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 0b841733 Lorenzo Miniero
* [libsrtp](https://github.com/cisco/libsrtp) (at least v1.5 suggested)
25 be35facb meetecho
* [Sofia-SIP](http://sofia-sip.sourceforge.net/)
26 2522507f Saúl Ibarra Corretgé
* [usrsctp](https://github.com/sctplab/usrsctp) (only needed if you
27 af40a682 meetecho
are interested in Data Channels)
28 20cbbc67 meetecho
* [libmicrohttpd](http://www.gnu.org/software/libmicrohttpd/) (only
29
needed if you are interested in REST support for the Janus API)
30 f500ae8e meetecho
* [libwebsockets](https://libwebsockets.org/) (only needed if
31 20cbbc67 meetecho
you are interested in WebSockets support for the Janus API)
32 f500ae8e meetecho
* [cmake](http://www.cmake.org/) (only needed if you are interested in
33
WebSockets support, as libwebsockets makes use of it)
34 ead45815 meetecho
* [rabbitmq-c](https://github.com/alanxz/rabbitmq-c) (only needed if
35 20cbbc67 meetecho
you are interested in RabbitMQ support for the Janus API)
36 be35facb meetecho
37
A couple of plugins depend on a few more libraries:
38
39
* [libopus](http://opus-codec.org/) (only needed for the bridge plugin)
40
* [libogg](http://xiph.org/ogg/) (only needed for the voicemail plugin)
41
42
Additionally, you'll need the following libraries and tools:
43
44
* [GLib](http://library.gnome.org/devel/glib/)
45
* [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/)
46
* [gengetopt](http://www.gnu.org/software/gengetopt/)
47
48
All of those libraries are usually available on most of the most common
49
distributions. Installing these libraries on a recent Fedora, for
50
instance, is very simple:
51
52
    yum install libmicrohttpd-devel jansson-devel libnice-devel \
53
       openssl-devel libsrtp-devel sofia-sip-devel glib-devel \
54 2512456f Lorenzo Miniero
       opus-devel libogg-devel pkgconfig gengetopt libtool autoconf automake
55 be35facb meetecho
56
On Ubuntu or Debian, it would require something like this:
57
58
	aptitude install libmicrohttpd-dev libjansson-dev libnice-dev \
59
		libssl-dev libsrtp-dev libsofia-sip-ua-dev libglib2.0-dev \
60 2512456f Lorenzo Miniero
		libopus-dev libogg-dev pkg-config gengetopt libtool automake
61 be35facb meetecho
62 e8271bd6 meetecho
* *Note:* please notice that libopus may not be available out of the box
63
on Ubuntu or Debian, unless you're using a recent version (e.g., Ubuntu
64
14.04 LTS). In that case, you'll have to [install it manually](http://www.opus-codec.org).
65 be35facb meetecho
66 a3464c2f meetecho
If your distro ships a pre-1.5 version of libsrtp, it may be better to
67
uninstall that version and [install 1.5 manually](https://github.com/cisco/libsrtp/releases).
68
In fact, 1.4.x is known to cause several issues with WebRTC. Installation
69
is quite straightforward:
70
71
	wget https://github.com/cisco/libsrtp/archive/v1.5.0.tar.gz
72
	tar xfv v1.5.0.tar.gz
73
	cd libsrtp-1.5.0
74
	./configure --prefix=/usr --enable-openssl
75
	make libsrtp.so && sudo make install
76
77
* *Note:* you may need to pass --libdir=/usr/lib64 to the configure
78
script if you're installing on a x86_64 distribution.
79
80 f4155719 Lorenzo Miniero
If you want to make use of BoringSSL instead of OpenSSL for any reason
81
(read [here](https://github.com/meetecho/janus-gateway/issues/136) for
82
some background on this), you'll have to manually install a specific
83
version of the library to a specific location. Use the following steps:
84
85
	git clone https://boringssl.googlesource.com/boringssl
86
	cd boringssl
87
	# We need a specific revision
88 f4afb9ba Lorenzo Miniero
	git checkout 12fe1b25ead258858309d22ffa9e1f9a316358d7
89 f4155719 Lorenzo Miniero
	# Don't barf on errors
90
	sed -i s/" -Werror"//g CMakeLists.txt
91
	# Build
92
	mkdir -p build
93
	cd build
94
	cmake -DCMAKE_CXX_FLAGS="-lrt" ..
95
	make
96
	cd ..
97
	# Install
98
	sudo mkdir -p /opt/boringssl
99
	sudo cp -R include /opt/boringssl/
100
	sudo mkdir -p /opt/boringssl/lib
101
	sudo cp build/ssl/libssl.a /opt/boringssl/lib/
102
	sudo cp build/crypto/libcrypto.a /opt/boringssl/lib/
103
104
Once the library is installed, you'll have to pass an additional
105
```--enable-boringssl``` flag to the configure script, as by default
106
Janus will be build assuming OpenSSL will be used. If you were using
107
OpenSSL and want to switch to BoringSSL, make sure you also do a
108
```make clean``` in the Janus folder before compiling with the new
109
BoringSSL support.
110
111 a3d13e20 meetecho
For what concerns usrsctp, which is needed for Data Channels support, it
112 05bba746 meetecho
is usually not available in repositories, so if you're interested in
113
them (support is optional) you'll have to install it manually. It is a
114
pretty easy and standard process:
115 a3d13e20 meetecho
116 2522507f Saúl Ibarra Corretgé
	git clone https://github.com/sctplab/usrsctp
117 a3d13e20 meetecho
	cd usrsctp
118
	./bootstrap
119
	./configure --prefix=/usr && make && sudo make install
120 2522507f Saúl Ibarra Corretgé
121 a3d13e20 meetecho
* *Note:* you may need to pass --libdir=/usr/lib64 to the configure
122
script if you're installing on a x86_64 distribution.
123
124 f500ae8e meetecho
The same applies for libwebsockets, which is needed for the optional
125 af40a682 meetecho
WebSockets support. If you're interested in supporting WebSockets to
126
control Janus, as an alternative (or replacement) to the default plain
127 f500ae8e meetecho
HTTP REST API, you'll have to install it manually:
128
129
	git clone git://git.libwebsockets.org/libwebsockets
130
	cd libwebsockets
131
	mkdir build
132
	cd build
133 20cbbc67 meetecho
	cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr -DCMAKE_C_FLAGS="-fpic" ..
134 f500ae8e meetecho
	make && sudo make install
135 211da807 meetecho
136
* *Note:* if libwebsockets.org is unreachable for any reason, replace
137
the first line with this:
138
139
	git clone https://github.com/warmcat/libwebsockets.git
140
141 ead45815 meetecho
Finally, the same can be said for rabbitmq-c as well, which is needed
142
for the optional RabbitMQ support. In fact, several different versions
143
of the library can be found, and the versions usually available in most
144
distribution repositories are not up-do-date with respect to the current
145
state of the development. As such, if you're interested in integrating
146
RabbitMQ queues as an alternative (or replacement) to HTTP and/or
147
WebSockets to control Janus, you can install the latest version with the
148
following steps:
149
150 5cdda711 meetecho
	git clone https://github.com/alanxz/rabbitmq-c
151
	cd rabbitmq-c
152
	git submodule init
153
	git submodule update
154
	autoreconf -i
155
	./configure --prefix=/usr && make && sudo make install
156 ead45815 meetecho
157
* *Note:* you may need to pass --libdir=/usr/lib64 to the configure
158
script if you're installing on a x86_64 distribution.
159
160
To conclude, should you be interested in building the gateway
161
documentation as well, you'll need some additional tools too:
162 be35facb meetecho
163
* [Doxygen](http://www.doxygen.org)
164
* [Graphviz](http://www.graphviz.org/)
165
166
On Fedora:
167
168
	yum install doxygen graphviz
169
170
On Ubuntu/Debian:
171
172
	aptitude install doxygen graphviz
173
174
175
##Compile
176 7dc04da4 meetecho
Once you have installed all the dependencies, get the code:
177
178
	git clone https://github.com/meetecho/janus-gateway.git
179
	cd janus-gateway
180
181
Then just use:
182 be35facb meetecho
183 ea61ba1b meetecho
	sh autogen.sh
184 be35facb meetecho
185 47dacad9 meetecho
to generate the configure file. After that, configure and compile as
186 ea61ba1b meetecho
usual to start the whole compilation process:
187 af40a682 meetecho
188 ea61ba1b meetecho
	./configure --prefix=/opt/janus
189
	make
190
	make install
191 05bba746 meetecho
192 c94052c2 meetecho
To also automatically install the default configuration files to use,
193
also do a:
194
195
	make configs
196 ead45815 meetecho
197
If you're not interested in Data Channels, WebSockets and/or RabbitMQ
198
(or you don't care about either of them) you can disable them when
199
configuring: 
200 05bba746 meetecho
201 ead45815 meetecho
	./configure --disable-websockets --disable-data-channels --disable-rabbitmq
202 a3d13e20 meetecho
203 ea61ba1b meetecho
If Doxygen and graphviz are available, the process will also build the
204
documentation for you. If you prefer not to build it, use the
205
--disable-docs configuration option:
206
207
	./configure --disable-docs
208
209
You can also selectively enable/disable other features (e.g., specific
210
plugins you don't care about). Use the --help option when configuring
211
for more info.
212 be35facb meetecho
213
214
##Configure and start
215
To start the gateway, you can use the janus executable. There are several
216
things you can configure, either in a configuration file:
217
218 ea61ba1b meetecho
	<installdir>/etc/janus/janus.cfg
219 be35facb meetecho
220
or on the command line:
221
222 ea61ba1b meetecho
	<installdir>/bin/janus --help
223 be35facb meetecho
	
224 20cbbc67 meetecho
	janus 0.1.0
225 be35facb meetecho
226
	Usage: janus [OPTIONS]...
227
228
	-h, --help                    Print help and exit
229
	-V, --version                 Print version and exit
230 7091a464 Lorenzo Miniero
	-b, --daemon                  Launch Janus in background as a daemon
231
                                  (default=off)
232 f82a8605 Lorenzo Miniero
	-N, --disable-stdout          Disable stdout based logging  (default=off)
233
	-L, --log-file=path           Log to the specified file (default=stdout only)
234 be35facb meetecho
	-i, --interface=ipaddress     Interface to use (will be the public IP)
235
	-P, --plugins-folder=path     Plugins folder (default=./plugins)
236 bb114ece Dustin Oprea
	-C, --config=filename         Configuration file to use
237 be35facb meetecho
	-F, --configs-folder=path     Configuration files folder (default=./conf)
238
	-c, --cert-pem=filename       HTTPS/DTLS certificate
239
	-k, --cert-key=filename       HTTPS/DTLS certificate key
240
	-S, --stun-server=filename    STUN server(:port) to use, if needed (e.g., 
241
								  gateway behind NAT, default=none)
242 4b131434 Lorenzo Miniero
	-1, --nat-1-1=ip              Public IP to put in all host candidates,
243
                                  assuming a 1:1 NAT is in place (e.g., Amazon
244
                                  EC2 instances, default=none)
245 c27a34be Lorenzo Miniero
	-E, --ice-enforce-list=list   Comma-separated list of the only interfaces to
246
                                  use for ICE gathering; partial strings are
247
                                  supported (e.g., eth0 or eno1,wlan0,
248
                                  default=none)
249 ddc1f702 meetecho
	-X, --ice-ignore-list=list    Comma-separated list of interfaces or IP 
250
                                  addresses to ignore for ICE gathering; 
251
                                  partial strings are supported (e.g., 
252
                                  vmnet8,192.168.0.1,10.0.0.1 or 
253
                                  vmnet,192.168., default=vmnet)
254 58d8bf1a meetecho
	-6, --ipv6-candidates         Whether to enable IPv6 candidates or not 
255
                                  (experimental)  (default=off)
256
	-l, --libnice-debug           Whether to enable libnice debugging or not  
257
                                  (default=off)
258 b4359229 meetecho
	-I, --ice-lite                Whether to enable the ICE Lite mode or not  
259
                                  (default=off)
260 11b11a8e meetecho
	-T, --ice-tcp                 Whether to enable ICE-TCP or not (warning: only
261
                                  works with ICE Lite)
262 b4359229 meetecho
                                  (default=off)
263 284646a9 meetecho
	-U, --bundle                  Whether to force BUNDLE or not (whether audio, 
264
                                  video and data will always be bundled)  
265
                                  (default=off)
266
	-u, --rtcp-mux                Whether to force rtcp-mux or not (whether RTP 
267
                                  and RTCP will always be muxed)  (default=off)
268 47dacad9 meetecho
	-q, --max-nack-queue=number   Maximum size of the NACK queue per user for 
269
                                  retransmissions
270 1d0190ba meetecho
	-r, --rtp-port-range=min-max  Port range to use for RTP/RTCP (only available
271
								  if the installed libnice supports it)
272 3a26e009 meetecho
	-d, --debug-level=1-7         Debug/logging level (0=disable debugging, 
273
                                  7=maximum debug level; default=4)
274 4c5c403a meetecho
	-D, --debug-timestamps        Enable debug/logging timestamps  (default=off)
275 6089eb4e Lorenzo Miniero
	-o, --disable-colors          Disable color in the logging  (default=off)
276 aff9f5c0 meetecho
	-a, --apisecret=randomstring  API secret all requests need to pass in order 
277
                                  to be accepted by Janus (useful when wrapping 
278
                                  Janus API requests in a server, none by 
279
                                  default)
280 263ce349 Lorenzo Miniero
	-A, --token-auth              Enable token-based authentication for all
281
                                  requests  (default=off)
282 be35facb meetecho
283
Options passed through the command line have the precedence on those
284
specified in the configuration file. To start the gateway, simply run:
285
286 ea61ba1b meetecho
	<installdir>/bin/janus
287 be35facb meetecho
288
This will start the gateway, and have it look at the configuration file.
289
By default, only an HTTP webserver is started. To enable HTTPS support,
290
edit the configuration file accordingly or use the command line. The
291
webserver will make use of the same certificates provided for DTLS. You
292
can also change the base path that the webserver uses: by default this
293
is /janus, but you can change it to anything you want and with any nesting
294
you want (e.g., /mypath, /my/path, or /my/really/nested/path). This is
295
done to allow you to more easily customize rules in any frontend you
296 af40a682 meetecho
may have (e.g., Apache in front of your services). Please notice that
297
the path configuration has no effect on the WebSockets usage of the API,
298
instead, as it is not needed there.
299 be35facb meetecho
 
300
In the absence of a configuration file, the only mandatory options to
301
specify in the command line are the ones related to the DTLS certificate.
302
A default certificate is provided with this package in the certs folder,
303
which you can use launching the executable with these parameters:
304
305 ea61ba1b meetecho
	<installdir>/bin/janus -c /path/to/mycert.pem -k /path/to/mycert.key
306 be35facb meetecho
307
At this point, the gateway will be listening on the 8088 port (or whatever
308
you changed that to) of your machine. To test whether it's working
309
correctly, you can use the demos provided with this package in the html
310
folder: these are exactly the same demos available online on the
311
[project website](http://janus.conf.meetecho.com/). Just copy the file
312
it contains in a webserver, and open the index.html page in either
313
Chrome or Firefox. A list of demo pages exploiting the different plugins
314
will be available.
315
316
317
##Help us!
318
Any thought, feedback or (hopefully not!) insult is welcome!
319
320
Developed by [@meetecho](https://github.com/meetecho)