Statistics
| Branch: | Revision:

janus-gateway / README.md @ ea61ba1b

History | View | Annotate | Download (10.6 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
* [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
* [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

    
33
A couple of plugins depend on a few more libraries:
34

    
35
* [libopus](http://opus-codec.org/) (only needed for the bridge plugin)
36
* [libogg](http://xiph.org/ogg/) (only needed for the voicemail plugin)
37

    
38
Additionally, you'll need the following libraries and tools:
39

    
40
* [GLib](http://library.gnome.org/devel/glib/)
41
* [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/)
42
* [gengetopt](http://www.gnu.org/software/gengetopt/)
43

    
44
All of those libraries are usually available on most of the most common
45
distributions. Installing these libraries on a recent Fedora, for
46
instance, is very simple:
47

    
48
    yum install libmicrohttpd-devel jansson-devel libnice-devel \
49
       openssl-devel libsrtp-devel sofia-sip-devel glib-devel \
50
       opus-devel libogg-devel libini_config-devel pkg-config gengetopt
51

    
52
On Ubuntu or Debian, it would require something like this:
53

    
54
	aptitude install libmicrohttpd-dev libjansson-dev libnice-dev \
55
		libssl-dev libsrtp-dev libsofia-sip-ua-dev libglib2.0-dev \
56
		libopus-dev libogg-dev libini-config-dev libcollection-dev \
57
		pkg-config gengetopt
58

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

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

    
68
	svn co http://sctp-refimpl.googlecode.com/svn/trunk/KERN/usrsctp usrsctp
69
	cd usrsctp
70
	./bootstrap
71
	./configure --prefix=/usr && make && sudo make install
72
	
73
* *Note:* you may need to pass --libdir=/usr/lib64 to the configure
74
script if you're installing on a x86_64 distribution.
75

    
76
The same applies for libwebsock, which is needed for the optional
77
WebSockets support. If you're interested in supporting WebSockets to
78
control Janus, as an alternative (or replacement) to the default plain
79
HTTP REST API, you'll have to install the version ```1.0.4``` manually:
80

    
81
	wget http://paydensutherland.com/libwebsock-1.0.4.tar.gz
82
	tar xfv libwebsock-1.0.4.tar.gz
83
	cd libwebsock-1.0.4
84
	./configure --prefix=/usr && make && sudo make install
85
	
86
* *Note:* you may need to pass --libdir=/usr/lib64 to the configure
87
script if you're installing on a x86_64 distribution.
88

    
89
Please notice that you have to install version ```1.0.4``` and not any
90
later version. In fact, recent versions of libwebsock added support for
91
threading in the library, but it is currently experimental and doesn't
92
work as expected in Janus.
93

    
94
Should you be interested in building the gateway documentation as well,
95
you'll need an additional component installed too:
96

    
97
* [Doxygen](http://www.doxygen.org)
98
* [Graphviz](http://www.graphviz.org/)
99

    
100
On Fedora:
101

    
102
	yum install doxygen graphviz
103

    
104
On Ubuntu/Debian:
105

    
106
	aptitude install doxygen graphviz
107

    
108

    
109
##Compile
110
Once you have installed all the dependencies, just use:
111

    
112
	sh autogen.sh
113

    
114
to generate the configure file. After that, configure and compile as
115
usual to start the whole compilation process:
116

    
117
	./configure --prefix=/opt/janus
118
	make
119
	make install
120

    
121
If you're not interested in Data Channels or WebSockets (or you don't
122
care about either of them) you can disable them when configuring: 
123

    
124
	./configure --disable-websockets --disable-data-channels
125

    
126
If Doxygen and graphviz are available, the process will also build the
127
documentation for you. If you prefer not to build it, use the
128
--disable-docs configuration option:
129

    
130
	./configure --disable-docs
131

    
132
You can also selectively enable/disable other features (e.g., specific
133
plugins you don't care about). Use the --help option when configuring
134
for more info.
135

    
136

    
137
##Configure and start
138
To start the gateway, you can use the janus executable. There are several
139
things you can configure, either in a configuration file:
140

    
141
	<installdir>/etc/janus/janus.cfg
142

    
143
or on the command line:
144

    
145
	<installdir>/bin/janus --help
146
	
147
	janus 0.0.5
148

    
149
	Usage: janus [OPTIONS]...
150

    
151
	-h, --help                    Print help and exit
152
	-V, --version                 Print version and exit
153
	-i, --interface=ipaddress     Interface to use (will be the public IP)
154
	-p, --port=portnumber         Web server HTTP port (default=8088)
155
	-s, --secure-port=portnumber  Web server HTTPS port (default=no HTTPS)
156
	-n, --no-http                 Disable insecure HTTP web server  (default=off)
157
	-b, --base-path=basepath      Base path to bind to in the web server 
158
								  (default=/janus) 
159
	-w, --ws-port=portnumber      WebSockets server port (default=no WebSockets)
160
	-W, --ws-secure-port=portnumber
161
                                  Secure WebSockets server port (default=no 
162
                                  secure WebSockets)
163
	-N, --no-websockets           Disable insecure WebSockets server  
164
                                  (default=off)
165
	-m, --admin-port=portnumber   Admin/monitor web server HTTP port 
166
                                  (default=7088)
167
	-M, --admin-secure-port=portnumber
168
                                  Admin/monitor web server HTTPS port (default=no 
169
                                  HTTPS)
170
	-O, --no-admin                Disable insecure HTTP admin/monitor web server  
171
                                  (default=off)
172
	-B, --admin-base-path=basepath
173
                                  Base path to bind to in the HTTP/HTTPS 
174
                                  admin/monitor web server (default=/admin) 
175
	-Q, --admin-secret=randomstring
176
                                  Admin/monitor secret all requests need to pass 
177
                                  in order to be accepted by Janus (useful a 
178
                                  crude form of authentication, none by 
179
                                  default)
180
	-L, --admin-acl=list          Comma-separated list of IP addresses allowed to 
181
                                  use the Admin/monitor; partial strings are 
182
                                  supported (e.g., 192.168.0.1,10.0.0.1 or 
183
                                  192.168., default=no restriction)
184
	-P, --plugins-folder=path     Plugins folder (default=./plugins)
185
	-C, --config=filename         Configuration file to use
186
	-F, --configs-folder=path     Configuration files folder (default=./conf)
187
	-c, --cert-pem=filename       HTTPS/DTLS certificate
188
	-k, --cert-key=filename       HTTPS/DTLS certificate key
189
	-S, --stun-server=filename    STUN server(:port) to use, if needed (e.g., 
190
								  gateway behind NAT, default=none)
191
	-X, --ice-ignore-list=list    Comma-separated list of interfaces or IP 
192
                                  addresses to ignore for ICE gathering; 
193
                                  partial strings are supported (e.g., 
194
                                  vmnet8,192.168.0.1,10.0.0.1 or 
195
                                  vmnet,192.168., default=vmnet)
196
	-e, --public-ip=ipaddress     Public address of the machine, to use in SDP
197
	-r, --rtp-port-range=min-max  Port range to use for RTP/RTCP (only available
198
								  if the installed libnice supports it)
199
	-d, --debug-level=1-7         Debug/logging level (0=disable debugging, 
200
                                  7=maximum debug level; default=4)
201
	-a, --apisecret=randomstring  API secret all requests need to pass in order 
202
                                  to be accepted by Janus (useful when wrapping 
203
                                  Janus API requests in a server, none by 
204
                                  default)
205

    
206
Options passed through the command line have the precedence on those
207
specified in the configuration file. To start the gateway, simply run:
208

    
209
	<installdir>/bin/janus
210

    
211
This will start the gateway, and have it look at the configuration file.
212
By default, only an HTTP webserver is started. To enable HTTPS support,
213
edit the configuration file accordingly or use the command line. The
214
webserver will make use of the same certificates provided for DTLS. You
215
can also change the base path that the webserver uses: by default this
216
is /janus, but you can change it to anything you want and with any nesting
217
you want (e.g., /mypath, /my/path, or /my/really/nested/path). This is
218
done to allow you to more easily customize rules in any frontend you
219
may have (e.g., Apache in front of your services). Please notice that
220
the path configuration has no effect on the WebSockets usage of the API,
221
instead, as it is not needed there.
222
 
223
In the absence of a configuration file, the only mandatory options to
224
specify in the command line are the ones related to the DTLS certificate.
225
A default certificate is provided with this package in the certs folder,
226
which you can use launching the executable with these parameters:
227

    
228
	<installdir>/bin/janus -c /path/to/mycert.pem -k /path/to/mycert.key
229

    
230
At this point, the gateway will be listening on the 8088 port (or whatever
231
you changed that to) of your machine. To test whether it's working
232
correctly, you can use the demos provided with this package in the html
233
folder: these are exactly the same demos available online on the
234
[project website](http://janus.conf.meetecho.com/). Just copy the file
235
it contains in a webserver, and open the index.html page in either
236
Chrome or Firefox. A list of demo pages exploiting the different plugins
237
will be available.
238

    
239

    
240
##Help us!
241
Any thought, feedback or (hopefully not!) insult is welcome!
242

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