icecast-server/doc/icecast2_listenerauth.html

<?xml version="1.0"?>
<!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.x Documentation</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<body>
<div class="boxtest">
<h1>Icecast 2 Listener Authentication</h1>
<hr id='titlebar' />
<br />
<br />
<br />
<h2>Listener Authentication</h2>
<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 &lt;mount&gt;
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>
<p>The listener authentication within a specified mount in the icecast XML configuration
can apply to either to a stream from a source client, relay or a webroot based file. They
do apply to intro files or fallback streams.
</p>
<br />
<h2>HTPASSWD Listener Authentication</h2>
<p>In order to use listener authentication, you MUST configure a mount specific option.  This means that you have to provide a &lt;mount&gt; section in the main icecast config file.  The following is an example :</p>
<pre>
    &lt;mount&gt;
        &lt;mount-name&gt;/example.ogg&lt;/mount-name&gt;
        &lt;authentication type="htpasswd"&gt;
                &lt;option name="filename" value="myauth"/&gt;
                &lt;option name="allow_duplicate_users" value="0"/&gt;
        &lt;/authentication&gt;
    &lt;/mount&gt;
</pre>
<p>To support listener authentication you MUST provide at a minimum &lt;mount-name&gt; and &lt;authentication&gt;.  The mount-name is the name of the mountpoint that you will use to connect your source client with and authentication configures what type of icecast2 authenticator to use.  Currently, only a single type "htpasswd" is implemented.  New authenticators will be added later.  Each authenticator has a variable number of options that are required and these are specified as shown in the example.  The htpasswd authenticator requires a few parameters.  The first, filename, specifies the name of the file to use to store users and passwords.  Note that this file need not exist (and probably will not exist when you first set it up).  Icecast has built-in support for managing users and passwords via the web admin interface.  More on this later in this section.  The second option, allow_duplicate_users, if set to 0, will prevent multiple connections using the same username.  Setting this value to 1 will enable mutltiple connections from the same username on a given mountpoint.  Note there is no way to specify a "max connections" for a particular user.
</p>
<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 />
<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" />
<p>You will see a lock in front of all mountpoint configured for listener authentication.  Also note that this page will only show CONNECTED mountpoints.</p>
<p>To manage users and passwords for this mountpoint, click on the lock or follow the "Manage Authentication" link.  The following screen will be shown :</p>
<img src="listener_auth2.jpg" alt="Screenshot of Manage Authentication" />
<p>This screen will show all the users configured for this mountpoint.  Adding users is as simple as entering a username and password in the fields and clicking "Add New User".  Note that usernames MUST be unique and there are NO restrictions on passwords.  You can delete users by clicking the appropriate delete link next to each user.</p>
<br />
<br />
<br />
<h3>Finishing it all off</h3>
<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 form that you can use for this purpose.  This page (http://server:port/auth.xsl) will bring up a form that users can use to enter their username and password.</p>
<img src="listener_auth3.jpg" alt="Screenshot of http://server:port/auth.xsl" />
<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 response headers can be sent back. libcurl is used for the requesting so 
https connections may be possible, but be aware of the extra overhead involved.</p>
<p>The useragent sent in each curl request will represent the icecast server version. The
response headers will depend on whether the listener is to be accepted.  In the case of
rejection, a response header <pre>icecast-auth-message: reason </pre> should also be returned
for placing in the log files.
</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 &lt;mount&gt; section in the main icecast
config file.  The following shows the list of options available :</p>
<pre>
    &lt;mount&gt;
        &lt;mount-name&gt;/example.ogg&lt;/mount-name&gt;
        &lt;authentication type="url"&gt;
            &lt;option name="mount_add" value="http://myauthserver.com/stream_start.php"/&gt;
            &lt;option name="mount_remove" value="http://myauthserver.com/stream_end.php"/&gt;
            &lt;option name="listener_add" value="http://myauthserver.com/listener_joined.php"/&gt;
            &lt;option name="listener_remove" value="http://myauthserver.com/listener_left.php"/&gt;
            &lt;option name="username" value="user"/&gt;
            &lt;option name="password" value="pass"/&gt;
            &lt;option name="auth_header" value="icecast-auth-user: 1"/&gt;
            &lt;option name="timelimit_header" value="icecast-auth-timelimit:"/&gt;
        &lt;/authentication&gt;
    &lt;/mount&gt;
</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>mount_add</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=mount_add&amp;mount=/live&amp;server=myserver.com&amp;port=8000
</pre>
<p>Here the details indicate the server name (&lt;hostname&gt;) and mountpoint starting up</p>
<h3>mount_remove</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=mount_remove&amp;mount=/live&amp;server=myserver.com&amp;port=8000
</pre>
<p>like the start option, server name and mountpoint are provided</p>
</p>
<h3>listener_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 may be stated in the 'header' option
</p>
<p>POST details are</p>
<pre>
    action=listener_add&amp;server=myserver.com&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;ip=127.0.0.1&amp;agent="My%20player"
</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&amp;session=xyz, but
note that each option data is escaped before being passed via POST
</p>
<h3>listener_remove</h3>
<p>This URL is for when a listener connection closes.</p>
<p>POST details are</p>
<pre>
    action=listener_remove&amp;server=myserver.com&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;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>auth_header</h3>
<p>The expected response header to be returned that allows the authencation to take
place may be specified here. The default is 
<pre>icecast-auth-user: 1</pre>
but it could can anything you like, for instance
<pre>HTTP 200 OK</pre>
<h3>timelimit_header</h3>
<p>Listeners could have a time limit imposed on them, and if this header is sent back with a
figure (which represents seconds) then that is how long the client will remain connected for.
</p>
<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.  Winamp/XMMS as least support the passing of query 
parameters, other players may also do</p>
</div>
</body>
</html>
- convert icecast documentation to xhtml - clean up html code - sync index.html with README svn path=/icecast/trunk/icecast/; revision=7786 2004-09-18 10:31:39 -04:00			`<?xml version="1.0"?>`
			`<!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>`
Make HTML title non-version specific.. Add a new "changes" page which enumerates major feature/fixes for each version.. We are starting with 2.3. svn path=/icecast/trunk/icecast/; revision=9762 2005-08-16 22:40:29 -04:00			`<title>Icecast v2.x Documentation</title>`
- convert icecast documentation to xhtml - clean up html code - sync index.html with README svn path=/icecast/trunk/icecast/; revision=7786 2004-09-18 10:31:39 -04:00			`<link rel="stylesheet" type="text/css" href="style.css" />`
			`</head>`
			`<body>`
			`<div class="boxtest">`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`<h1>Icecast 2 Listener Authentication</h1>`
replace table with hr+css svn path=/icecast/trunk/icecast/; revision=7791 2004-09-18 16:14:50 -04:00			`<hr id='titlebar' />`
- convert icecast documentation to xhtml - clean up html code - sync index.html with README svn path=/icecast/trunk/icecast/; revision=7786 2004-09-18 10:31:39 -04:00			`<br />`
			`<br />`
			`<br />`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`<h2>Listener Authentication</h2>`
changes applied from feedback. make option names and action settings more consistent. Add changes to docs for listener auth via url svn path=/icecast/trunk/icecast/; revision=9768 2005-08-17 12:38:46 -04:00			`<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>`
- convert icecast documentation to xhtml - clean up html code - sync index.html with README svn path=/icecast/trunk/icecast/; revision=7786 2004-09-18 10:31:39 -04:00			`<br />`
changes applied from feedback. make option names and action settings more consistent. Add changes to docs for listener auth via url svn path=/icecast/trunk/icecast/; revision=9768 2005-08-17 12:38:46 -04:00			`<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>`
			`<p>The listener authentication within a specified mount in the icecast XML configuration`
			`can apply to either to a stream from a source client, relay or a webroot based file. They`
			`do apply to intro files or fallback streams.`
			`</p>`
- convert icecast documentation to xhtml - clean up html code - sync index.html with README svn path=/icecast/trunk/icecast/; revision=7786 2004-09-18 10:31:39 -04:00			`<br />`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`<h2>HTPASSWD Listener Authentication</h2>`
			`<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>`
changes applied from feedback. make option names and action settings more consistent. Add changes to docs for listener auth via url svn path=/icecast/trunk/icecast/; revision=9768 2005-08-17 12:38:46 -04:00			`<mount-name>/example.ogg</mount-name>`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`<authentication type="htpasswd">`
			`<option name="filename" value="myauth"/>`
added ability to disallow concurrent connections from the same username if using htpasswd listener authentication. svn path=/icecast/trunk/icecast/; revision=6711 2004-05-17 00:33:46 -04:00			`<option name="allow_duplicate_users" value="0"/>`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`</authentication>`
			`</mount>`
			`</pre>`
added ability to disallow concurrent connections from the same username if using htpasswd listener authentication. svn path=/icecast/trunk/icecast/; revision=6711 2004-05-17 00:33:46 -04:00			<p>To support listener authentication you MUST provide at a minimum <mount-name> and <authentication>. The mount-name is the name of the mountpoint that you will use to connect your source client with and authentication configures what type of icecast2 authenticator to use. Currently, only a single type "htpasswd" is implemented. New authenticators will be added later. Each authenticator has a variable number of options that are required and these are specified as shown in the example. The htpasswd authenticator requires a few parameters. The first, filename, specifies the name of the file to use to store users and passwords. Note that this file need not exist (and probably will not exist when you first set it up). Icecast has built-in support for managing users and passwords via the web admin interface. More on this later in this section. The second option, allow_duplicate_users, if set to 0, will prevent multiple connections using the same username. Setting this value to 1 will enable mutltiple connections from the same username on a given mountpoint. Note there is no way to specify a "max connections" for a particular user.
This Page Tentatively Validates As XHTML 1.0 Strict (Tentatively Valid)! svn path=/icecast/trunk/icecast/; revision=7792 2004-09-18 17:01:39 -04:00			`</p>`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`<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>`
- convert icecast documentation to xhtml - clean up html code - sync index.html with README svn path=/icecast/trunk/icecast/; revision=7786 2004-09-18 10:31:39 -04:00			`<br />`
			`<br />`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`<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>`
This Page Tentatively Validates As XHTML 1.0 Strict (Tentatively Valid)! svn path=/icecast/trunk/icecast/; revision=7792 2004-09-18 17:01:39 -04:00			`<img src="listener_auth1.jpg" alt="Screenshot of http://server:ip/admin/stats.xsl" />`
doc updates, and some minor changes for the sample conf files. svn path=/icecast/trunk/icecast/; revision=14437 2008-01-28 22:24:47 -05:00			`<p>You will see a lock in front of all mountpoint configured for listener authentication. Also note that this page will only show CONNECTED mountpoints.</p>`
			`<p>To manage users and passwords for this mountpoint, click on the lock or follow the "Manage Authentication" link. The following screen will be shown :</p>`
This Page Tentatively Validates As XHTML 1.0 Strict (Tentatively Valid)! svn path=/icecast/trunk/icecast/; revision=7792 2004-09-18 17:01:39 -04:00			`<img src="listener_auth2.jpg" alt="Screenshot of Manage Authentication" />`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`<p>This screen will show all the users configured for this mountpoint. Adding users is as simple as entering a username and password in the fields and clicking "Add New User". Note that usernames MUST be unique and there are NO restrictions on passwords. You can delete users by clicking the appropriate delete link next to each user.</p>`
- convert icecast documentation to xhtml - clean up html code - sync index.html with README svn path=/icecast/trunk/icecast/; revision=7786 2004-09-18 10:31:39 -04:00			`<br />`
			`<br />`
			`<br />`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`<h3>Finishing it all off</h3>`
			`<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 form that you can use for this purpose. This page (http://server:port/auth.xsl) will bring up a form that users can use to enter their username and password.</p>`
This Page Tentatively Validates As XHTML 1.0 Strict (Tentatively Valid)! svn path=/icecast/trunk/icecast/; revision=7792 2004-09-18 17:01:39 -04:00			`<img src="listener_auth3.jpg" alt="Screenshot of http://server:port/auth.xsl" />`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`<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>`
- convert icecast documentation to xhtml - clean up html code - sync index.html with README svn path=/icecast/trunk/icecast/; revision=7786 2004-09-18 10:31:39 -04:00			`<br />`
			`<br />`
changes applied from feedback. make option names and action settings more consistent. Add changes to docs for listener auth via url svn path=/icecast/trunk/icecast/; revision=9768 2005-08-17 12:38:46 -04:00			`<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 response headers can be sent back. libcurl is used for the requesting so`
			`https connections may be possible, but be aware of the extra overhead involved.</p>`
			`<p>The useragent sent in each curl request will represent the icecast server version. The`
			`response headers will depend on whether the listener is to be accepted. In the case of`
			`rejection, a response header <pre>icecast-auth-message: reason </pre> should also be returned`
			`for placing in the log files.`
			`</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="mount_add" value="http://myauthserver.com/stream_start.php"/>`
			`<option name="mount_remove" value="http://myauthserver.com/stream_end.php"/>`
			`<option name="listener_add" value="http://myauthserver.com/listener_joined.php"/>`
			`<option name="listener_remove" value="http://myauthserver.com/listener_left.php"/>`
			`<option name="username" value="user"/>`
			`<option name="password" value="pass"/>`
			`<option name="auth_header" value="icecast-auth-user: 1"/>`
			`<option name="timelimit_header" value="icecast-auth-timelimit:"/>`
			`</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>mount_add</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=mount_add&mount=/live&server=myserver.com&port=8000`
			`</pre>`
			`<p>Here the details indicate the server name (<hostname>) and mountpoint starting up</p>`
			`<h3>mount_remove</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=mount_remove&mount=/live&server=myserver.com&port=8000`
			`</pre>`
			`<p>like the start option, server name and mountpoint are provided</p>`
			`</p>`
			`<h3>listener_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 may be stated in the 'header' option`
			`</p>`
			`<p>POST details are</p>`
			`<pre>`
			`action=listener_add&server=myserver.com&port=8000&client=1&mount=/live&user=&pass=&ip=127.0.0.1&agent="My%20player"`
			`</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>listener_remove</h3>`
			`<p>This URL is for when a listener connection closes.</p>`
			`<p>POST details are</p>`
			`<pre>`
			`action=listener_remove&server=myserver.com&port=8000&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>auth_header</h3>`
			`<p>The expected response header to be returned that allows the authencation to take`
			`place may be specified here. The default is`
			`<pre>icecast-auth-user: 1</pre>`
			`but it could can anything you like, for instance`
			`<pre>HTTP 200 OK</pre>`
			`<h3>timelimit_header</h3>`
			`<p>Listeners could have a time limit imposed on them, and if this header is sent back with a`
			`figure (which represents seconds) then that is how long the client will remain connected for.`
			`</p>`
- convert icecast documentation to xhtml - clean up html code - sync index.html with README svn path=/icecast/trunk/icecast/; revision=7786 2004-09-18 10:31:39 -04:00			`<br />`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`<h2>A note about players and authentication</h2>`
changes applied from feedback. make option names and action settings more consistent. Add changes to docs for listener auth via url svn path=/icecast/trunk/icecast/; revision=9768 2005-08-17 12:38:46 -04:00			`<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>`
much better documentation of listener authentication svn path=/icecast/trunk/icecast/; revision=6617 2004-05-03 11:00:18 -04:00			`</div>`
			`</body>`
			`</html>`