Debian Codegraph @

doc/auth/index.html

raw
1 <!DOCTYPE html>
2 <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
3 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
4 <head>
5 <meta charset="utf-8">
6 <meta http-equiv="X-UA-Compatible" content="IE=edge">
7 <meta name="viewport" content="width=device-width, initial-scale=1.0">
8
9
10 <link rel="shortcut icon" href="../img/favicon.ico">
11 <title>Authentication - Icecast Docs</title>
12 <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
13
14 <link rel="stylesheet" href="../css/theme.css" type="text/css" />
15 <link rel="stylesheet" href="../css/theme_extra.css" type="text/css" />
16 <link rel="stylesheet" href="../css/highlight.css">
17
18 <script>
19 // Current page data
20 var mkdocs_page_name = "Authentication";
21 var mkdocs_page_input_path = "auth.md";
22 var mkdocs_page_url = "/auth/";
23 </script>
24
25 <script src="../js/jquery-2.1.1.min.js"></script>
26 <script src="../js/modernizr-2.8.3.min.js"></script>
27 <script type="text/javascript" src="../js/highlight.pack.js"></script>
28
29 </head>
30
31 <body class="wy-body-for-nav" role="document">
32
33 <div class="wy-grid-for-nav">
34
35
36 <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
37 <div class="wy-side-nav-search">
38 <a href=".." class="icon icon-home"> Icecast Docs</a>
39
40 </div>
41
42 <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
43 <ul class="current">
44
45
46 <li class="toctree-l1">
47
48 <a class="" href="..">Introduction</a>
49 </li>
50
51 <li class="toctree-l1">
52
53 <a class="" href="../basic_setup/">Basic Setup</a>
54 </li>
55
56 <li class="toctree-l1">
57
58 <a class="" href="../config_file/">Configuration File</a>
59 </li>
60
61 <li class="toctree-l1">
62
63 <a class="" href="../server_stats/">Server Statistics</a>
64 </li>
65
66 <li class="toctree-l1 current">
67
68 <a class="current" href="./">Authentication</a>
69 <ul class="subnav">
70
71 <li class="toctree-l2"><a href="#listener-authentication">Listener Authentication</a></li>
72
73
74 <li class="toctree-l2"><a href="#htpasswd-listener-authentication">htpasswd Listener Authentication</a></li>
75
76 <ul>
77
78 <li><a class="toctree-l3" href="#configuring-users-and-passwords">Configuring Users and Passwords</a></li>
79
80 <li><a class="toctree-l3" href="#finishing-it-all-off">Finishing it all off</a></li>
81
82 </ul>
83
84
85 <li class="toctree-l2"><a href="#url">URL</a></li>
86
87 <ul>
88
89 <li><a class="toctree-l3" href="#mount_add">mount_add</a></li>
90
91 <li><a class="toctree-l3" href="#mount_remove">mount_remove</a></li>
92
93 <li><a class="toctree-l3" href="#listener_add">listener_add</a></li>
94
95 <li><a class="toctree-l3" href="#listener_remove">listener_remove</a></li>
96
97 <li><a class="toctree-l3" href="#stream_auth">stream_auth</a></li>
98
99 <li><a class="toctree-l3" href="#other-options">Other Options</a></li>
100
101 </ul>
102
103
104 <li class="toctree-l2"><a href="#a-note-about-players-and-authentication">A note about players and authentication</a></li>
105
106
107 <li class="toctree-l2"><a href="#source-authentication">Source Authentication</a></li>
108
109 <ul>
110
111 <li><a class="toctree-l3" href="#url-authentication-stream_auth">URL authentication: stream_auth</a></li>
112
113 </ul>
114
115
116 </ul>
117 </li>
118
119 <li class="toctree-l1">
120
121 <a class="" href="../relaying/">Relaying</a>
122 </li>
123
124 <li class="toctree-l1">
125
126 <a class="" href="../yp/">Listing in a YellowPage Directory</a>
127 </li>
128
129 <li class="toctree-l1">
130
131 <a class="" href="../admin_interface/">Admin Interface</a>
132 </li>
133
134 <li class="toctree-l1">
135
136 <a class="" href="../win32/">Windows Specific</a>
137 </li>
138
139 </ul>
140 </div>
141 &nbsp;
142 </nav>
143
144 <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
145
146
147 <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
148 <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
149 <a href="..">Icecast Docs</a>
150 </nav>
151
152
153 <div class="wy-nav-content">
154 <div class="rst-content">
155 <div role="navigation" aria-label="breadcrumbs navigation">
156 <ul class="wy-breadcrumbs">
157 <li><a href="..">Docs</a> &raquo;</li>
158
159
160
161 <li>Authentication</li>
162 <li class="wy-breadcrumbs-aside">
163
164 </li>
165 </ul>
166 <hr/>
167 </div>
168 <div role="main">
169 <div class="section">
170
171 <h1 id="listener-authentication">Listener Authentication</h1>
172 <p>Listener authentication is a feature of Icecast which allows you to secure a certain mountpoint such that in order to listen,
173 a listener must pass some verification test. With this feature, a simple pay-for-play operation (eg. user/pass), or some filtering
174 based on the listener connection can be performed. This section will show you the basics of setting up and maintaining this component. </p>
175 <p>To define listener authentication, a group of tags are specified in the <code>&lt;mount&gt;</code> group relating to the mountpoint. This means
176 that authentication can apply to listeners of source clients or relays. </p>
177 <p>The following authentication mechanisms can apply to listeners:</p>
178 <!-- FIXME -->
179
180 <ul>
181 <li>htpasswd: lookup a named file for a matching username and password</li>
182 <li>URL: issue web requests (eg. PHP) to match authentication</li>
183 </ul>
184 <p>The listener authentication within a specified mount in the icecast XML configuration can apply to either to a stream from a
185 source client, relay or a webroot based file. They do apply to intro files or fallback streams.</p>
186 <h1 id="htpasswd-listener-authentication">htpasswd Listener Authentication</h1>
187 <p>In order to use listener authentication, you <strong>must</strong> configure a mount specific option. This means that you have to provide
188 a <code>&lt;mount&gt;</code> section in the main icecast config file. The following is an example:</p>
189 <!-- FIXME -->
190
191 <pre><code class="xml">&lt;mount&gt;
192 &lt;mount-name&gt;/example.ogg&lt;/mount-name&gt;
193 &lt;authentication type=&quot;htpasswd&quot;&gt;
194 &lt;option name=&quot;filename&quot; value=&quot;myauth&quot;/&gt;
195 &lt;option name=&quot;allow_duplicate_users&quot; value=&quot;0&quot;/&gt;
196 &lt;/authentication&gt;
197 &lt;/mount&gt;
198 </code></pre>
199
200 <p>To support listener authentication you <strong>must</strong> provide at a minimum <code>&lt;mount-name&gt;</code> and <code>&lt;authentication&gt;</code>.<br />
201 The <code>mount-name</code> is the name of the mountpoint that you will use to connect your source client with and <code>authentication</code> configures
202 what type of Icecast authenticator to use.<br />
203 Currently, only <code>htpasswd</code> and <code>url</code> are implemented. Each authenticator has a variable number of options that are required and
204 these are specified as shown in the example.<br />
205 The htpasswd authenticator requires a few parameters:<br />
206 The first, <code>filename</code>, specifies the name of the file to use to store users and passwords. Note that this file need not exist
207 (and probably will not exist when you first set it up).<br />
208 Icecast has built-in support for managing users and passwords via the web admin interface. More on this later in this section.<br />
209 The second option, <code>allow_duplicate_users</code>, if set to <code>0</code>, will prevent multiple connections using the same username. Setting this
210 value to <code>1</code> will enable mutltiple connections from the same username on a given mountpoint.<br />
211 Note there is no way to specify a “max connections” for a particular user. </p>
212 <p>Icecast supports a mixture of streams that require listener authentication and those that do not.</p>
213 <h2 id="configuring-users-and-passwords">Configuring Users and Passwords</h2>
214 <p>Once the appropriate entries are made to the config file, connect your source client (using the mountpoint you named in
215 the config file). To configure users and passwords for this stream you must use the web-based admin interface. Navigate to
216 <code>http://server:ip/admin/stats.xsl</code> to begin. If you have configured everything properly, you should see a screen like the
217 following:</p>
218 <p><img alt="Screenshot of Admin Stats" src="../img/listener_auth1.png" /></p>
219 <p>You will see a lock in front of all mountpoint configured for listener authentication. Also note that this page will
220 only show <em>connected</em> mountpoints.</p>
221 <p>To manage users and passwords for this mountpoint, click on the “Manage Authentication” link. The following screen will be shown:</p>
222 <p><img alt="Screenshot of Manage Authentication" src="../img/listener_auth2.png" /></p>
223 <p>This screen will show all the users configured for this mountpoint. Adding users is as simple as entering a username and password
224 in the fields and clicking “Add”.<br />
225 Note that usernames <strong>must</strong> be unique and there are <strong>no</strong> restrictions on passwords. You can delete users by clicking the appropriate
226 delete link next to each user.</p>
227 <h2 id="finishing-it-all-off">Finishing it all off</h2>
228 <p>Ok, so you've created your users, and you have everything setup properly, how do your users login? Well, we've provided a simple login
229 form that you can use for this purpose. This page (<code>http://server:port/auth.xsl</code>) will bring up a form that users can use to enter their
230 username and password.</p>
231 <p><img alt="Screenshot of Auth Page" src="../img/listener_auth3.png" /></p>
232 <p>This page will serve a m3u with the username and password and in most cases should open the correct media player and begin playing
233 your stream.</p>
234 <h1 id="url">URL</h1>
235 <p>Authenticating listeners via the URL method involves Icecast, when a listener connects, issuing requests to a web server
236 and checking the response headers. If a certain header is sent back then the listener connecting is allowed to continue,
237 if not, an error is sent back to the listener. </p>
238 <p>The URLs specified will invoke some web server scripts like PHP to do any work that they may choose to do. All that is
239 required of the scripting language is that POST information can be handled and response headers can be sent back.<br />
240 libcurl is used for the requesting so https connections may be possible, but be aware of the extra overhead involved. </p>
241 <p>The useragent sent in each curl request will represent the Icecast server version. The response headers will depend on
242 whether the listener is to be accepted. In the case of rejection, a response header<br />
243 <code>Icecast-Auth-Message: Reason</code><br />
244 should also be returned for placing in the log files. </p>
245 <p>In order to use URL based listener authentication, you <strong>must</strong> configure a mount specific option. This means that you
246 have to provide a <code>&lt;mount&gt;</code> section in the main Icecast config file. The following shows the list of options available: </p>
247 <!-- FIXME -->
248
249 <pre><code class="xml">&lt;mount&gt;
250 &lt;mount-name&gt;/example.ogg&lt;/mount-name&gt;
251 &lt;authentication type=&quot;url&quot;&gt;
252 &lt;option name=&quot;mount_add&quot; value=&quot;http://auth.example.org/stream_start.php&quot;/&gt;
253 &lt;option name=&quot;mount_remove&quot; value=&quot;http://auth.example.org/stream_end.php&quot;/&gt;
254 &lt;option name=&quot;listener_add&quot; value=&quot;http://auth.example.org/listener_joined.php&quot;/&gt;
255 &lt;option name=&quot;listener_remove&quot; value=&quot;http://auth.example.org/listener_left.php&quot;/&gt;
256 &lt;option name=&quot;username&quot; value=&quot;user&quot;/&gt;
257 &lt;option name=&quot;password&quot; value=&quot;pass&quot;/&gt;
258 &lt;option name=&quot;auth_header&quot; value=&quot;icecast-auth-user: 1&quot;/&gt;
259 &lt;option name=&quot;timelimit_header&quot; value=&quot;icecast-auth-timelimit:&quot;/&gt;
260 &lt;option name=&quot;headers&quot; value=&quot;x-pragma,x-token&quot;/&gt;
261 &lt;option name=&quot;header_prefix&quot; value=&quot;ClientHeader.&quot;/&gt;
262 &lt;option name=&quot;stream_auth&quot; value=&quot;http://auth.example.org/source.php&quot;/&gt;
263 &lt;/authentication&gt;
264 &lt;/mount&gt;
265 </code></pre>
266
267 <p>The options are described below in more detail, each of which is optional, but in each case, within the POST data,
268 the value for each setting is encoded.</p>
269 <!-- FIXME -->
270
271 <h2 id="mount_add">mount_add</h2>
272 <p>This URL is for informing the auth server of a stream starting. No listener information is passed for this,
273 but it can be used to initialise any details the auth server may have. </p>
274 <h3 id="post-details">POST Details</h3>
275 <dl>
276 <dt>action</dt>
277 <dd><code>mount_add</code></dd>
278 <dt>mount</dt>
279 <dd>the mountpoint starting up</dd>
280 <dt>server</dt>
281 <dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
282 <dt>port</dt>
283 <dd>the server port</dd>
284 </dl>
285 <h3 id="example">Example</h3>
286 <p><code>action=mount_add&amp;mount=/live&amp;server=icecast.example.org&amp;port=8000</code></p>
287 <h2 id="mount_remove">mount_remove</h2>
288 <p>This URL is for informing the auth server of a stream finishing, like the start option, no listener details
289 are passed. </p>
290 <h3 id="post-details_1">POST Details</h3>
291 <dl>
292 <dt>action</dt>
293 <dd><code>mount_remove</code></dd>
294 <dt>mount</dt>
295 <dd>the mountpoint being removed</dd>
296 <dt>server</dt>
297 <dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
298 <dt>port</dt>
299 <dd>the server port</dd>
300 </dl>
301 <h3 id="example_1">Example</h3>
302 <p><code>action=mount_remove&amp;mount=/live&amp;server=icecast.example.org&amp;port=8000</code></p>
303 <h2 id="listener_add">listener_add</h2>
304 <p>This is most likely to be used if anything. When a listener connects, before anything is sent back to them, this
305 request is processed. The default action is to reject a listener unless the auth server sends back a response header
306 which may be stated in the <code>header</code> option.</p>
307 <h3 id="post-details_2">POST Details</h3>
308 <dl>
309 <dt>action</dt>
310 <dd><code>listener_add</code></dd>
311 <dt>mount</dt>
312 <dd>the mountpoint, including query parameters</dd>
313 <dt>server</dt>
314 <dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
315 <dt>port</dt>
316 <dd>the server port</dd>
317 <dt>user</dt>
318 <dd>user as stated in listener HTTP basic auth<br />
319 <em>May be blank</em></dd>
320 <dt>pass</dt>
321 <dd>pass as stated in listener HTTP basic auth
322 <em>May be blank</em></dd>
323 <dt>client</dt>
324 <dd>unique ID for the client within Icecast</dd>
325 <dt>ip</dt>
326 <dd>listeners IP address</dd>
327 <dt>agent</dt>
328 <dd>useragent from the listeners player</dd>
329 </dl>
330 <p><strong>Note:</strong> The mount here (unlike the start/end options) states the requested url including any query parameters,
331 so for instance the requested URL can be <code>/stream.ogg&amp;session=xyz</code>, but note that each option data is
332 escaped before being passed via POST.</p>
333 <h3 id="example_2">Example</h3>
334 <p><code>action=listener_add&amp;server=icecast.example.org&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;ip=127.0.0.1&amp;agent=My%20player</code> </p>
335 <h2 id="listener_remove">listener_remove</h2>
336 <p>This URL is for when a listener connection closes.</p>
337 <h3 id="post-details_3">POST Details</h3>
338 <dl>
339 <dt>action</dt>
340 <dd><code>listener_remove</code></dd>
341 <dt>mount</dt>
342 <dd>the mountpoint</dd>
343 <dt>server</dt>
344 <dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
345 <dt>port</dt>
346 <dd>the server port</dd>
347 <dt>user</dt>
348 <dd>user as stated in listener HTTP basic auth<br />
349 <em>May be blank</em></dd>
350 <dt>pass</dt>
351 <dd>pass as stated in listener HTTP basic auth
352 <em>May be blank</em></dd>
353 <dt>client</dt>
354 <dd>unique ID for the client within Icecast</dd>
355 <dt>ip</dt>
356 <dd>listeners IP address</dd>
357 <dt>agent</dt>
358 <dd>useragent from the listeners player</dd>
359 <dt>duration</dt>
360 <dd>number of seconds the listener was connected for</dd>
361 </dl>
362 <h3 id="example_3">Example</h3>
363 <p><code>action=listener_remove&amp;server=icecast.example.org&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;duration=3600&amp;ip=127.0.0.1&amp;agent=My%20player</code></p>
364 <h2 id="stream_auth">stream_auth</h2>
365 <p>Technically this does not belong to listener authentication, but due to its similarity it is explained here too.<br />
366 When a source connects, before anything is sent back to them, this request is processed. The default action is to
367 reject a source unless the auth server sends back a response header which may be stated in the <code>header</code> option.</p>
368 <h3 id="post-details_4">POST Details</h3>
369 <dl>
370 <dt>action</dt>
371 <dd><code>stream_auth</code></dd>
372 <dt>mount</dt>
373 <dd>the mountpoint</dd>
374 <dt>server</dt>
375 <dd>hostname of the Icecast server the client tries to connect to</dd>
376 <dt>port</dt>
377 <dd>the port of said server</dd>
378 <dt>user</dt>
379 <dd>username as sent by the source client</dd>
380 <dt>pass</dt>
381 <dd>password as sent by the source client</dd>
382 <dt>admin</dt>
383 <dd>admin request (read below)</dd>
384 </dl>
385 <p><strong>Note:</strong> As admin requests can come in for a stream (eg. metadata update) these requests can be issued while
386 stream is active. For these <code>admin</code> is set to <code>1</code> in POST details.</p>
387 <h3 id="example_4">Example</h3>
388 <p><code>action=stream_auth&amp;mount=/stream.ogg&amp;ip=192.0.2.0&amp;server=icecast.example.org&amp;port=8000&amp;user=source&amp;pass=password&amp;admin=1</code></p>
389 <h2 id="other-options">Other Options</h2>
390 <dl>
391 <dt>auth_header</dt>
392 <dd>The expected response header to be returned that allows the authencation to take place may be specified here.<br />
393 The default is:<br />
394 <code>icecast-auth-user: 1</code><br />
395 but it could be anything you like, for instance:<br />
396 <code>HTTP 200 OK</code></dd>
397 <dt>timelimit_header</dt>
398 <dd>Listeners could have a time limit imposed on them, and if this header is sent back with a figure (which represents seconds)
399 then that is how long the client will remain connected for.</dd>
400 <dt>headers</dt>
401 <dd>This is a list of HTTP headers provided by the client which should be passed to the authencation service.
402 Those headers are prepended by the value of header_prefix and sent as POST parameters.</dd>
403 <dt>header_prefix</dt>
404 <dd>This is the prefix used for passing client headers. See headers for details.</dd>
405 </dl>
406 <h1 id="a-note-about-players-and-authentication">A note about players and authentication</h1>
407 <p>We do not have an exaustive list of players that support listener authentication.<br />
408 We use standard HTTP basic authentication, and in general, many media players support this if they support anything at all.
409 Winamp and Foobar2000 support HTTP basic authentication on Windows, and XMMS supports it on UNIX platforms. Winamp/XMMS at
410 least support the passing of query parameters, other players may also do.</p>
411 <h1 id="source-authentication">Source Authentication</h1>
412 <p>Source authentication is a feature of Icecast which allows you to secure a certain mountpoint such that in order to stream to it,
413 a source client must pass some verification test. This section will show you the basics of setting up and maintaining this component.<br />
414 To define source authentication, a group of tags are specified in the <code>&lt;mount&gt;</code> group relating to the mountpoint. </p>
415 <p>The following authentication mechanisms can apply to sources:</p>
416 <!-- FIXME -->
417
418 <ul>
419 <li>BASIC: <code>&lt;password&gt;</code> and possibly <code>&lt;username&gt;</code> in the <code>&lt;mount&gt;</code> section</li>
420 <li>URL: issue web requests (eg. PHP) to match authentication</li>
421 </ul>
422 <h2 id="url-authentication-stream_auth">URL authentication: <code>stream_auth</code></h2>
423 <p>A <code>&lt;mount&gt;</code> can contain a section <code>&lt;authentication type="url"&gt;</code> and therein
424 <code>&lt;option name="stream_auth" value="http://auth.example.org/source.php"/&gt;</code>. When a source connects, before anything is sent back to
425 them, this request is processed. The default action is to reject a source unless the auth server sends back a response header which may
426 be stated in the <code>header</code> option (same as listener auth). </p>
427 <h3 id="post-details_5">POST Details</h3>
428 <dl>
429 <dt>action</dt>
430 <dd><code>stream_auth</code></dd>
431 <dt>mount</dt>
432 <dd>the mountpoint</dd>
433 <dt>server</dt>
434 <dd>hostname of the Icecast server the client tries to connect to</dd>
435 <dt>port</dt>
436 <dd>the port of said server</dd>
437 <dt>user</dt>
438 <dd>username as sent by the source client</dd>
439 <dt>pass</dt>
440 <dd>password as sent by the source client</dd>
441 <dt>admin</dt>
442 <dd>admin request (read below)</dd>
443 </dl>
444 <p><strong>Note:</strong> As admin requests can come in for a stream (eg. metadata update) these requests can be issued while
445 stream is active. For these <code>admin</code> is set to <code>1</code> in POST details.</p>
446 <h3 id="example_5">Example</h3>
447 <p><code>action=stream_auth&amp;mount=/stream.ogg&amp;ip=192.0.2.0&amp;server=icecast.example.org&amp;port=8000&amp;user=source&amp;pass=password&amp;admin=1</code></p>
448
449 </div>
450 </div>
451 <footer>
452
453 <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
454
455 <a href="../relaying/" class="btn btn-neutral float-right" title="Relaying">Next <span class="icon icon-circle-arrow-right"></span></a>
456
457
458 <a href="../server_stats/" class="btn btn-neutral" title="Server Statistics"><span class="icon icon-circle-arrow-left"></span> Previous</a>
459
460 </div>
461
462
463 <hr/>
464
465 <div role="contentinfo">
466 <!-- Copyright etc -->
467
468 </div>
469
470 Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
471 </footer>
472
473 </div>
474 </div>
475
476 </section>
477
478 </div>
479
480 <div class="rst-versions" role="note" style="cursor: pointer">
481 <span class="rst-current-version" data-toggle="rst-current-version">
482
483
484 <span><a href="../server_stats/" style="color: #fcfcfc;">&laquo; Previous</a></span>
485
486
487 <span style="margin-left: 15px"><a href="../relaying/" style="color: #fcfcfc">Next &raquo;</a></span>
488
489 </span>
490 </div>
491 <script>var base_url = '..';</script>
492 <script src="../js/theme.js"></script>
493
494 </body>
495 </html>