Statistics
| Branch: | Revision:

janus-gateway / README.md @ 11b11a8e

History | View | Annotate | Download (13.3 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
* [libmicrohttpd](http://www.gnu.org/software/libmicrohttpd/)
22
* [libini-config](https://fedorahosted.org/sssd/) (INI configurations)
23
* [Jansson](http://www.digip.org/jansson/)
24
* [libnice](http://nice.freedesktop.org/wiki/)
25
* [OpenSSL](http://www.openssl.org/) (at least v1.0.1e)
26
* [libsrtp](http://srtp.sourceforge.net/srtp.html)
27
* [Sofia-SIP](http://sofia-sip.sourceforge.net/)
28 af40a682 meetecho
* [usrsctp](http://code.google.com/p/sctp-refimpl/) (only needed if you
29
are interested in Data Channels)
30
* [libwebsock](https://github.com/payden/libwebsock) (only needed if
31
you are interested in WebSockets support)
32 fa50eb5d meetecho
* [libevent](http://libevent.org/) (only needed if you are interested in
33
WebSockets support, as libwebsock makes use of it)
34 ead45815 meetecho
* [rabbitmq-c](https://github.com/alanxz/rabbitmq-c) (only needed if
35
you are interested in RabbitMQ support)
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 fbbf4fbb meetecho
       opus-devel libogg-devel libini_config-devel pkg-config gengetopt \
55
       libtool autoconf automake
56 be35facb meetecho
57
On Ubuntu or Debian, it would require something like this:
58
59
	aptitude install libmicrohttpd-dev libjansson-dev libnice-dev \
60
		libssl-dev libsrtp-dev libsofia-sip-ua-dev libglib2.0-dev \
61 bc604887 Dustin Oprea
		libopus-dev libogg-dev libini-config-dev libcollection-dev \
62 65091379 Graeme
		pkg-config gengetopt libtool automake
63 be35facb meetecho
64 e8271bd6 meetecho
* *Note:* please notice that libopus may not be available out of the box
65
on Ubuntu or Debian, unless you're using a recent version (e.g., Ubuntu
66
14.04 LTS). In that case, you'll have to [install it manually](http://www.opus-codec.org).
67 be35facb meetecho
68 a3d13e20 meetecho
For what concerns usrsctp, which is needed for Data Channels support, it
69 05bba746 meetecho
is usually not available in repositories, so if you're interested in
70
them (support is optional) you'll have to install it manually. It is a
71
pretty easy and standard process:
72 a3d13e20 meetecho
73
	svn co http://sctp-refimpl.googlecode.com/svn/trunk/KERN/usrsctp usrsctp
74
	cd usrsctp
75
	./bootstrap
76
	./configure --prefix=/usr && make && sudo make install
77
	
78
* *Note:* you may need to pass --libdir=/usr/lib64 to the configure
79
script if you're installing on a x86_64 distribution.
80
81 af40a682 meetecho
The same applies for libwebsock, which is needed for the optional
82
WebSockets support. If you're interested in supporting WebSockets to
83
control Janus, as an alternative (or replacement) to the default plain
84
HTTP REST API, you'll have to install the version ```1.0.4``` manually:
85
86 5b8a8b0f meetecho
	git clone git://github.com/payden/libwebsock.git
87
	cd libwebsock
88
	git checkout tags/v1.0.4
89 8f1dd39c meetecho
	autoreconf -i
90 7e2a3879 meetecho
	./autogen.sh
91 af40a682 meetecho
	./configure --prefix=/usr && make && sudo make install
92
	
93
* *Note:* you may need to pass --libdir=/usr/lib64 to the configure
94
script if you're installing on a x86_64 distribution.
95
96 fa50eb5d meetecho
* *Note:* as anticipated you'll need to install libevent-dev (or
97
libevent-devel) before installing libwebsock
98
([see here for more info](https://groups.google.com/forum/#!searchin/meetecho-janus/websockets/meetecho-janus/TqPNJDsUf2s/uBhlT8a4WUMJ)).
99 404fe5fa Giacomo Vacca
100 af40a682 meetecho
Please notice that you have to install version ```1.0.4``` and not any
101
later version. In fact, recent versions of libwebsock added support for
102
threading in the library, but it is currently experimental and doesn't
103
work as expected in Janus.
104
105 ead45815 meetecho
Finally, the same can be said for rabbitmq-c as well, which is needed
106
for the optional RabbitMQ support. In fact, several different versions
107
of the library can be found, and the versions usually available in most
108
distribution repositories are not up-do-date with respect to the current
109
state of the development. As such, if you're interested in integrating
110
RabbitMQ queues as an alternative (or replacement) to HTTP and/or
111
WebSockets to control Janus, you can install the latest version with the
112
following steps:
113
114 5cdda711 meetecho
	git clone https://github.com/alanxz/rabbitmq-c
115
	cd rabbitmq-c
116
	git submodule init
117
	git submodule update
118
	autoreconf -i
119
	./configure --prefix=/usr && make && sudo make install
120 ead45815 meetecho
121
* *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
To conclude, should you be interested in building the gateway
125
documentation as well, you'll need some additional tools too:
126 be35facb meetecho
127
* [Doxygen](http://www.doxygen.org)
128
* [Graphviz](http://www.graphviz.org/)
129
130
On Fedora:
131
132
	yum install doxygen graphviz
133
134
On Ubuntu/Debian:
135
136
	aptitude install doxygen graphviz
137
138
139
##Compile
140 7dc04da4 meetecho
Once you have installed all the dependencies, get the code:
141
142
	git clone https://github.com/meetecho/janus-gateway.git
143
	cd janus-gateway
144
145
Then just use:
146 be35facb meetecho
147 ea61ba1b meetecho
	sh autogen.sh
148 be35facb meetecho
149 47dacad9 meetecho
to generate the configure file. After that, configure and compile as
150 ea61ba1b meetecho
usual to start the whole compilation process:
151 af40a682 meetecho
152 ea61ba1b meetecho
	./configure --prefix=/opt/janus
153
	make
154
	make install
155 05bba746 meetecho
156 c94052c2 meetecho
To also automatically install the default configuration files to use,
157
also do a:
158
159
	make configs
160 ead45815 meetecho
161
If you're not interested in Data Channels, WebSockets and/or RabbitMQ
162
(or you don't care about either of them) you can disable them when
163
configuring: 
164 05bba746 meetecho
165 ead45815 meetecho
	./configure --disable-websockets --disable-data-channels --disable-rabbitmq
166 a3d13e20 meetecho
167 ea61ba1b meetecho
If Doxygen and graphviz are available, the process will also build the
168
documentation for you. If you prefer not to build it, use the
169
--disable-docs configuration option:
170
171
	./configure --disable-docs
172
173
You can also selectively enable/disable other features (e.g., specific
174
plugins you don't care about). Use the --help option when configuring
175
for more info.
176 be35facb meetecho
177
178
##Configure and start
179
To start the gateway, you can use the janus executable. There are several
180
things you can configure, either in a configuration file:
181
182 ea61ba1b meetecho
	<installdir>/etc/janus/janus.cfg
183 be35facb meetecho
184
or on the command line:
185
186 ea61ba1b meetecho
	<installdir>/bin/janus --help
187 be35facb meetecho
	
188 1281ca86 meetecho
	janus 0.0.8
189 be35facb meetecho
190
	Usage: janus [OPTIONS]...
191
192
	-h, --help                    Print help and exit
193
	-V, --version                 Print version and exit
194
	-i, --interface=ipaddress     Interface to use (will be the public IP)
195
	-p, --port=portnumber         Web server HTTP port (default=8088)
196
	-s, --secure-port=portnumber  Web server HTTPS port (default=no HTTPS)
197
	-n, --no-http                 Disable insecure HTTP web server  (default=off)
198
	-b, --base-path=basepath      Base path to bind to in the web server 
199
								  (default=/janus) 
200 af40a682 meetecho
	-w, --ws-port=portnumber      WebSockets server port (default=no WebSockets)
201
	-W, --ws-secure-port=portnumber
202
                                  Secure WebSockets server port (default=no 
203
                                  secure WebSockets)
204
	-N, --no-websockets           Disable insecure WebSockets server  
205
                                  (default=off)
206 292d035f meetecho
	-m, --admin-port=portnumber   Admin/monitor web server HTTP port 
207
                                  (default=7088)
208
	-M, --admin-secure-port=portnumber
209
                                  Admin/monitor web server HTTPS port (default=no 
210
                                  HTTPS)
211
	-O, --no-admin                Disable insecure HTTP admin/monitor web server  
212
                                  (default=off)
213
	-B, --admin-base-path=basepath
214
                                  Base path to bind to in the HTTP/HTTPS 
215
                                  admin/monitor web server (default=/admin) 
216
	-Q, --admin-secret=randomstring
217
                                  Admin/monitor secret all requests need to pass 
218
                                  in order to be accepted by Janus (useful a 
219
                                  crude form of authentication, none by 
220
                                  default)
221
	-L, --admin-acl=list          Comma-separated list of IP addresses allowed to 
222
                                  use the Admin/monitor; partial strings are 
223
                                  supported (e.g., 192.168.0.1,10.0.0.1 or 
224
                                  192.168., default=no restriction)
225 be35facb meetecho
	-P, --plugins-folder=path     Plugins folder (default=./plugins)
226 bb114ece Dustin Oprea
	-C, --config=filename         Configuration file to use
227 be35facb meetecho
	-F, --configs-folder=path     Configuration files folder (default=./conf)
228
	-c, --cert-pem=filename       HTTPS/DTLS certificate
229
	-k, --cert-key=filename       HTTPS/DTLS certificate key
230
	-S, --stun-server=filename    STUN server(:port) to use, if needed (e.g., 
231
								  gateway behind NAT, default=none)
232 ddc1f702 meetecho
	-X, --ice-ignore-list=list    Comma-separated list of interfaces or IP 
233
                                  addresses to ignore for ICE gathering; 
234
                                  partial strings are supported (e.g., 
235
                                  vmnet8,192.168.0.1,10.0.0.1 or 
236
                                  vmnet,192.168., default=vmnet)
237 1d0190ba meetecho
	-e, --public-ip=ipaddress     Public address of the machine, to use in SDP
238 58d8bf1a meetecho
	-6, --ipv6-candidates         Whether to enable IPv6 candidates or not 
239
                                  (experimental)  (default=off)
240
	-l, --libnice-debug           Whether to enable libnice debugging or not  
241
                                  (default=off)
242 b4359229 meetecho
	-I, --ice-lite                Whether to enable the ICE Lite mode or not  
243
                                  (default=off)
244 11b11a8e meetecho
	-T, --ice-tcp                 Whether to enable ICE-TCP or not (warning: only
245
                                  works with ICE Lite)
246 b4359229 meetecho
                                  (default=off)
247 47dacad9 meetecho
	-q, --max-nack-queue=number   Maximum size of the NACK queue per user for 
248
                                  retransmissions
249 1d0190ba meetecho
	-r, --rtp-port-range=min-max  Port range to use for RTP/RTCP (only available
250
								  if the installed libnice supports it)
251 3a26e009 meetecho
	-d, --debug-level=1-7         Debug/logging level (0=disable debugging, 
252
                                  7=maximum debug level; default=4)
253 aff9f5c0 meetecho
	-a, --apisecret=randomstring  API secret all requests need to pass in order 
254
                                  to be accepted by Janus (useful when wrapping 
255
                                  Janus API requests in a server, none by 
256
                                  default)
257 ead45815 meetecho
	-R, --enable-rabbitmq         Enable RabbitMQ support  (default=off)
258
	-H, --rabbitmq-host=string    Address (host:port) of the RabbitMQ server to 
259
                                  use (default=localhost:5672)
260
	-t, --rabbitmq-in-queue=string
261
                                  Name of the RabbitMQ queue for incoming 
262
                                  messages (no default)
263
	-f, --rabbitmq-out-queue=string
264
                                  Name of the RabbitMQ queue for outgoing 
265
                                  messages (no default)
266 be35facb meetecho
267
Options passed through the command line have the precedence on those
268
specified in the configuration file. To start the gateway, simply run:
269
270 ea61ba1b meetecho
	<installdir>/bin/janus
271 be35facb meetecho
272
This will start the gateway, and have it look at the configuration file.
273
By default, only an HTTP webserver is started. To enable HTTPS support,
274
edit the configuration file accordingly or use the command line. The
275
webserver will make use of the same certificates provided for DTLS. You
276
can also change the base path that the webserver uses: by default this
277
is /janus, but you can change it to anything you want and with any nesting
278
you want (e.g., /mypath, /my/path, or /my/really/nested/path). This is
279
done to allow you to more easily customize rules in any frontend you
280 af40a682 meetecho
may have (e.g., Apache in front of your services). Please notice that
281
the path configuration has no effect on the WebSockets usage of the API,
282
instead, as it is not needed there.
283 be35facb meetecho
 
284
In the absence of a configuration file, the only mandatory options to
285
specify in the command line are the ones related to the DTLS certificate.
286
A default certificate is provided with this package in the certs folder,
287
which you can use launching the executable with these parameters:
288
289 ea61ba1b meetecho
	<installdir>/bin/janus -c /path/to/mycert.pem -k /path/to/mycert.key
290 be35facb meetecho
291
At this point, the gateway will be listening on the 8088 port (or whatever
292
you changed that to) of your machine. To test whether it's working
293
correctly, you can use the demos provided with this package in the html
294
folder: these are exactly the same demos available online on the
295
[project website](http://janus.conf.meetecho.com/). Just copy the file
296
it contains in a webserver, and open the index.html page in either
297
Chrome or Firefox. A list of demo pages exploiting the different plugins
298
will be available.
299
300
301
##Help us!
302
Any thought, feedback or (hopefully not!) insult is welcome!
303
304
Developed by [@meetecho](https://github.com/meetecho)