[xiph-commits] r9544 - in icecast/branches/kh/icecast: . doc
karl at svn.xiph.org
karl at svn.xiph.org
Sat Jul 2 09:21:32 PDT 2005
Author: karl
Date: 2005-07-02 09:21:26 -0700 (Sat, 02 Jul 2005)
New Revision: 9544
Modified:
icecast/branches/kh/icecast/NEWS
icecast/branches/kh/icecast/configure.in
icecast/branches/kh/icecast/doc/icecast2_listenerauth.html
Log:
bump version to kh12
Modified: icecast/branches/kh/icecast/NEWS
===================================================================
--- icecast/branches/kh/icecast/NEWS 2005-07-02 02:10:16 UTC (rev 9543)
+++ icecast/branches/kh/icecast/NEWS 2005-07-02 16:21:26 UTC (rev 9544)
@@ -20,6 +20,25 @@
. get feedback from people on listener auth via url, Stephen Nixon has done
some auth scripts that people can use at http://imux.net/icecast/
+2.2-kh12
+. rework connection handler to work on non-blocking sockets. the listener thread
+ handles the http reading, after which it passes it over to the connection
+ thread for parsing.
+. any xsl file can be placed in admin now and can work off the stats data
+. dump listener details to xml for admin requests that get the stats tree
+. make sure that fallback file streams are hidden
+. fix fd leak in error case for file ranges and plaintext list_mounts function
+ like that used for querying a master server
+. use correct offset from burst point for new clients
+. batch up small reads for passthrough streams into slightly larger blocks, so
+ that TCP protocol overhead is kept to a minimum.
+. because of the batching, the max send count per client per iteration is less
+. fixup streamlist.txt to be sent via fserve thread
+. fixup automatic m3u output to be via fserve thread.
+. XML read from HUP is not sent via the connection handler now, instead the
+ slave thread processes it
+. doc update for url listener auth
+
2.2-kh11
. xsl/xml pages from adminroot and webroot are now delivered via the file
serve thread.
Modified: icecast/branches/kh/icecast/configure.in
===================================================================
--- icecast/branches/kh/icecast/configure.in 2005-07-02 02:10:16 UTC (rev 9543)
+++ icecast/branches/kh/icecast/configure.in 2005-07-02 16:21:26 UTC (rev 9544)
@@ -1,4 +1,4 @@
-AC_INIT([Icecast], [2.2-kh11], [karl at xiph.org])
+AC_INIT([Icecast], [2.2-kh12], [karl at xiph.org])
AC_PREREQ(2.54)
AC_CONFIG_SRCDIR(src/main.c)
Modified: icecast/branches/kh/icecast/doc/icecast2_listenerauth.html
===================================================================
--- icecast/branches/kh/icecast/doc/icecast2_listenerauth.html 2005-07-02 02:10:16 UTC (rev 9543)
+++ icecast/branches/kh/icecast/doc/icecast2_listenerauth.html 2005-07-02 16:21:26 UTC (rev 9544)
@@ -2,7 +2,7 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
-<title>Icecast v2.0 Documentation</title>
+<title>Icecast v2.2 Documentation</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<body>
@@ -13,17 +13,26 @@
<br />
<br />
<h2>Listener Authentication</h2>
-<p>Listener authentication is a feature of icecast which allows you to secure certain mountpoint so that in order to listen, a listener must provide a username and password. With this feature a simple pay-for-play operation can be setup. This section will show you the basics of setting up and maintaining this component.</p>
-
+<p>Listener authentication is a feature of icecast which allows you to secure a certain
+mountpoint such that in order to listen, a listener must pass some verification test. With
+this feature, a simple pay-for-play operation (eg user/pass), or some filtering based on the
+listener connection can be performed. This section will show you the basics of setting up
+and maintaining this component.</p>
+<p>To define listener authentication, a group of tags are specified in the <mount>
+group relating to the mountpoint. This means that authentication can apply to listeners of
+source clients or relays.</p>
<br />
+<p>The following authentication mechanisms can apply to listeners</p>
+<ul>
+ <li>HTPASSWD - lookup a named file for a matching username and password</li>
+ <li>URL - issue web requests (eg PHP) to match authentication</li>
+</ul>
<br />
-<br />
<h2>HTPASSWD Listener Authentication</h2>
-<h3>Config File Entries</h3>
<p>In order to use listener authentication, you MUST configure a mount specific option. This means that you have to provide a <mount> section in the main icecast config file. The following is an example :</p>
<pre>
<mount>
- <mount-name>/example-complex.ogg</mount-name>
+ <mount-name>/example.ogg</mount-name>
<authentication type="htpasswd">
<option name="filename" value="myauth"/>
<option name="allow_duplicate_users" value="0"/>
@@ -35,7 +44,6 @@
<p>Icecast supports a mixture of streams that require listener authentication and those that do not. Only mounts that are named in the config file can be configured for listener authentication.</p>
<br />
<br />
-<br />
<h3>Configuring Users and Passwords</h3>
<p>Once the appropriate entries are made to the config file, connect your source client (using the mountpoint you named in the config file). To configure users and passwords for this stream you must use the web-based admin interface. Navigate to http://server:ip/admin/stats.xsl to begin. If you have configured everything properly, you should see a screen like the following :</p>
<img src="listener_auth1.jpg" alt="Screenshot of http://server:ip/admin/stats.xsl" />
@@ -52,9 +60,90 @@
<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 your stream</p>
<br />
<br />
+<h2>URL</h2>
+<p>Authenticating listeners via the URL method involves icecast, when a listener connects,
+issuing requests to a web server and checking the response headers. If a certain header is
+sent back then the listener connecting is allowed to continue, if not, an error is sent back
+to the listener.</p>
+<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 required of the scripting language is that POST information can
+be handled and a response header can be sent back. libcurl is used for the requesting so
+https connections can be used.</p>
+<p>In order to use URL based listener authentication, you MUST configure a mount specific
+option. This means that you have to provide a <mount> section in the main icecast
+config file. The following shows the list of options available :</p>
+<pre>
+ <mount>
+ <mount-name>/example.ogg</mount-name>
+ <authentication type="url">
+ <option name="start" value="http://myauthserver.com/stream_start.php"/>
+ <option name="end" value="http://myauthserver.com/stream_end.php"/>
+ <option name="add" value="http://myauthserver.com/listener_joined.php"/>
+ <option name="remove" value="http://myauthserver.com/listener_left.php"/>
+ <option name="username" value="user"/>
+ <option name="password" value="pass"/>
+ <option name="header" value="listener-validated: 1"/>
+ </authentication>
+ </mount>
+</pre>
+<p>The options are described below in more detail, each of which is optional, but in each
+case, within the POST data, the value for each setting is encoded.</p>
+<h3>start</h3>
+<p>This URL is for informing the auth server of a stream starting. No listener information
+is passed for this, but can be used to initialise any details the auth server may have.
+</p>
+<p>POST details are</p>
+<pre>
+ action=start&mount=/live&server=myserver.com
+</pre>
+<p>Here the details indicate the server name (<hostname>) and mountpoint starting up</p>
+<h3>end</h3>
+<p>This URL is for informing the auth server of a stream finishing, like the start option, no
+listener details are passed.</p>
+<p>POST details are</p>
+<pre>
+ action=end&mount=/live&server=myserver.com
+</pre>
+<p>like the start option, server name and mountpoint are provided</p>
+</p>
+<h3>add</h3>
+<p>This is most likely to be used if anything. When a listener connects, before anything is
+sent back to them, this request is processed. The default action is to reject a listener
+unless the auth server sends back a response header which is stated in the 'header' option
+</p>
+<p>POST details are</p>
+<pre>
+ action=auth&server=myserver.com&client=1&mount=/live&user=&pass=&ip=127.0.0.1&agent="My player"
+</pre>
+<p>There are more details with this, client is the unique ID for the client within icecast,
+user and pass may be blank but come from the HTTP basic auth that the listener states, ip
+is the listeners IP address and agent is the Useragent from the listeners player.</p>
+<p>The mount here (unlike the start/end options) states the requested url including any
+query parameters, so for instance the requested URL can be /stream.ogg&session=xyz, but
+note that each option data is escaped before being passed via POST
+</p>
+<h3>remove</h3>
+<p>This URL is for when a listener connection closes.</p>
+<p>POST details are</p>
+<pre>
+ action=remove&client=1&mount=/live&user=&pass=&duration=3600
+</pre>
+<p>Again this is similar to the add option, the difference being that a duration is passed
+reflecting the number of seconds the listener was connected for </p>
+<h3>header</h3>
+<p>The response header returned from these requests that allows the authencation to take
+place can be stated here. The default is
+<pre>icecast-auth-user: 1</pre>
+but it could can anything you wish for instance
+<pre>HTTP 200 OK</pre>
<br />
+<br />
<h2>A note about players and authentication</h2>
-<p>We do not have an exaustive list of players that support listener authentication. We use standard HTTP basic authentication, and in general, many media players support this if they support anything at all. Winamp and Foobar2000 support HTTP basic authentication on windows, and XMMS supports it on unix platforms.</p>
+<p>We do not have an exaustive list of players that support listener authentication. We use
+standard HTTP basic authentication, and in general, many media players support this if they
+support anything at all. Winamp and Foobar2000 support HTTP basic authentication on windows,
+and XMMS supports it on unix platforms. Winamp/XMMS as least support the passing of query
+parameters, other players may also do</p>
</div>
</body>
</html>
More information about the commits
mailing list