mirror of
https://gitlab.xiph.org/xiph/icecast-server.git
synced 2024-12-04 14:46:30 -05:00
360 lines
20 KiB
HTML
360 lines
20 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<title>Icecast Docs Docs — Authentication</title>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||
|
||
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
|
||
</head>
|
||
|
||
<body>
|
||
|
||
<div class="header">
|
||
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
|
||
</div>
|
||
|
||
<div class="section">
|
||
|
||
<h2>Icecast 2.4.99.1 Docs — Authentication</h2>
|
||
|
||
<div class="article">
|
||
<h3 id="listener-authentication">Listener Authentication</h3>
|
||
<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 <code><mount></code> group relating to the mountpoint. This means
|
||
that authentication can apply to listeners of source clients or relays. </p>
|
||
|
||
<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>
|
||
|
||
</div>
|
||
|
||
<div class="article">
|
||
<h3 id="htpasswd-listener-authentication">htpasswd Listener Authentication</h3>
|
||
<p>In order to use listener authentication, you <strong>must</strong> configure a mount specific option. This means that you have to provide
|
||
a <code><mount></code> section in the main icecast config file. The following is an example:</p>
|
||
|
||
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt"><mount></span>
|
||
<span class="nt"><mount-name></span>/example.ogg<span class="nt"></mount-name></span>
|
||
<span class="nt"><authentication</span> <span class="na">type=</span><span class="s">"htpasswd"</span><span class="nt">></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"filename"</span> <span class="na">value=</span><span class="s">"myauth"</span><span class="nt">/></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"allow_duplicate_users"</span> <span class="na">value=</span><span class="s">"0"</span><span class="nt">/></span>
|
||
<span class="nt"></authentication></span>
|
||
<span class="nt"></mount></span></code></pre></div>
|
||
|
||
<p>To support listener authentication you <strong>must</strong> provide at a minimum <code><mount-name></code> and <code><authentication></code>.<br />
|
||
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
|
||
what type of Icecast authenticator to use.<br />
|
||
Currently, only <code>htpasswd</code> and <code>url</code> are implemented. Each authenticator has a variable number of options that are required and
|
||
these are specified as shown in the example.<br />
|
||
The htpasswd authenticator requires a few parameters:<br />
|
||
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
|
||
(and probably will not exist when you first set it up).<br />
|
||
Icecast has built-in support for managing users and passwords via the web admin interface. More on this later in this section.<br />
|
||
The second option, <code>allow_duplicate_users</code>, if set to <code>0</code>, will prevent multiple connections using the same username. Setting this
|
||
value to <code>1</code> will enable mutltiple connections from the same username on a given mountpoint.<br />
|
||
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.</p>
|
||
|
||
<h4 id="configuring-users-and-passwords">Configuring Users and Passwords</h4>
|
||
<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
|
||
<code>http://server:ip/admin/stats.xsl</code> to begin. If you have configured everything properly, you should see a screen like the
|
||
following:</p>
|
||
|
||
<p><img src="img/listener_auth1.png" alt="Screenshot of Admin Stats" /></p>
|
||
|
||
<p>You will see a lock in front of all mountpoint configured for listener authentication. Also note that this page will
|
||
only show <em>connected</em> mountpoints.</p>
|
||
|
||
<p>To manage users and passwords for this mountpoint, click on the “Manage Authentication” link. The following screen will be shown:</p>
|
||
|
||
<p><img src="img/listener_auth2.png" alt="Screenshot of Manage Authentication" /></p>
|
||
|
||
<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”.<br />
|
||
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
|
||
delete link next to each user.</p>
|
||
|
||
<h4 id="finishing-it-all-off">Finishing it all off</h4>
|
||
<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 (<code>http://server:port/auth.xsl</code>) will bring up a form that users can use to enter their
|
||
username and password.</p>
|
||
|
||
<p><img src="img/listener_auth3.png" alt="Screenshot of Auth Page" /></p>
|
||
|
||
<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>
|
||
|
||
</div>
|
||
|
||
<div class="article">
|
||
<h3 id="url">URL</h3>
|
||
|
||
<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.<br />
|
||
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<br />
|
||
<code>Icecast-Auth-Message: Reason</code><br />
|
||
should also be returned for placing in the log files. </p>
|
||
|
||
<p>In order to use URL based listener authentication, you <strong>must</strong> configure a mount specific option. This means that you
|
||
have to provide a <code><mount></code> section in the main Icecast config file. The following shows the list of options available: </p>
|
||
|
||
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt"><mount></span>
|
||
<span class="nt"><mount-name></span>/example.ogg<span class="nt"></mount-name></span>
|
||
<span class="nt"><authentication</span> <span class="na">type=</span><span class="s">"url"</span><span class="nt">></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"mount_add"</span> <span class="na">value=</span><span class="s">"http://auth.example.org/stream_start.php"</span><span class="nt">/></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"mount_remove"</span> <span class="na">value=</span><span class="s">"http://auth.example.org/stream_end.php"</span><span class="nt">/></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"listener_add"</span> <span class="na">value=</span><span class="s">"http://auth.example.org/listener_joined.php"</span><span class="nt">/></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"listener_remove"</span> <span class="na">value=</span><span class="s">"http://auth.example.org/listener_left.php"</span><span class="nt">/></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"username"</span> <span class="na">value=</span><span class="s">"user"</span><span class="nt">/></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"password"</span> <span class="na">value=</span><span class="s">"pass"</span><span class="nt">/></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"auth_header"</span> <span class="na">value=</span><span class="s">"icecast-auth-user: 1"</span><span class="nt">/></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"timelimit_header"</span> <span class="na">value=</span><span class="s">"icecast-auth-timelimit:"</span><span class="nt">/></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"headers"</span> <span class="na">value=</span><span class="s">"x-pragma,x-token"</span><span class="nt">/></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"header_prefix"</span> <span class="na">value=</span><span class="s">"ClientHeader."</span><span class="nt">/></span>
|
||
<span class="nt"><option</span> <span class="na">name=</span><span class="s">"stream_auth"</span> <span class="na">value=</span><span class="s">"http://auth.example.org/source.php"</span><span class="nt">/></span>
|
||
<span class="nt"></authentication></span>
|
||
<span class="nt"></mount></span></code></pre></div>
|
||
|
||
<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>
|
||
|
||
<h4 id="mountadd">mount_add</h4>
|
||
|
||
<p>This URL is for informing the auth server of a stream starting. No listener information is passed for this,
|
||
but it can be used to initialise any details the auth server may have. </p>
|
||
|
||
<h5 id="post-details">POST Details</h5>
|
||
<dl>
|
||
<dt>action</dt>
|
||
<dd><code>mount_add</code></dd>
|
||
<dt>mount</dt>
|
||
<dd>the mountpoint starting up</dd>
|
||
<dt>server</dt>
|
||
<dd>the server name (<code><hostname></code>)</dd>
|
||
<dt>port</dt>
|
||
<dd>the server port</dd>
|
||
</dl>
|
||
|
||
<h5 id="example">Example</h5>
|
||
<p><code>action=mount_add&mount=/live&server=icecast.example.org&port=8000</code></p>
|
||
|
||
<h4 id="mountremove">mount_remove</h4>
|
||
<p>This URL is for informing the auth server of a stream finishing, like the start option, no listener details
|
||
are passed. </p>
|
||
|
||
<h5 id="post-details-1">POST Details</h5>
|
||
<dl>
|
||
<dt>action</dt>
|
||
<dd><code>mount_remove</code></dd>
|
||
<dt>mount</dt>
|
||
<dd>the mountpoint being removed</dd>
|
||
<dt>server</dt>
|
||
<dd>the server name (<code><hostname></code>)</dd>
|
||
<dt>port</dt>
|
||
<dd>the server port</dd>
|
||
</dl>
|
||
|
||
<h5 id="example-1">Example</h5>
|
||
<p><code>action=mount_remove&mount=/live&server=icecast.example.org&port=8000</code></p>
|
||
|
||
<h4 id="listeneradd">listener_add</h4>
|
||
<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 <code>header</code> option.</p>
|
||
|
||
<h5 id="post-details-2">POST Details</h5>
|
||
<dl>
|
||
<dt>action</dt>
|
||
<dd><code>listener_add</code></dd>
|
||
<dt>mount</dt>
|
||
<dd>the mountpoint, including query parameters</dd>
|
||
<dt>server</dt>
|
||
<dd>the server name (<code><hostname></code>)</dd>
|
||
<dt>port</dt>
|
||
<dd>the server port</dd>
|
||
<dt>user</dt>
|
||
<dd>user as stated in listener HTTP basic auth<br />
|
||
<em>May be blank</em></dd>
|
||
<dt>pass</dt>
|
||
<dd>pass as stated in listener HTTP basic auth
|
||
<em>May be blank</em></dd>
|
||
<dt>client</dt>
|
||
<dd>unique ID for the client within Icecast</dd>
|
||
<dt>ip</dt>
|
||
<dd>listeners IP address</dd>
|
||
<dt>agent</dt>
|
||
<dd>useragent from the listeners player</dd>
|
||
</dl>
|
||
|
||
<p><strong>Note:</strong> The mount here (unlike the start/end options) states the requested url including any query parameters,
|
||
so for instance the requested URL can be <code>/stream.ogg&session=xyz</code>, but note that each option data is
|
||
escaped before being passed via POST.</p>
|
||
|
||
<h5 id="example-2">Example</h5>
|
||
<p><code>action=listener_add&server=icecast.example.org&port=8000&client=1&mount=/live&user=&pass=&ip=127.0.0.1&agent=My%20player</code> </p>
|
||
|
||
<h4 id="listenerremove">listener_remove</h4>
|
||
<p>This URL is for when a listener connection closes.</p>
|
||
|
||
<h5 id="post-details-3">POST Details</h5>
|
||
<dl>
|
||
<dt>action</dt>
|
||
<dd><code>listener_remove</code></dd>
|
||
<dt>mount</dt>
|
||
<dd>the mountpoint</dd>
|
||
<dt>server</dt>
|
||
<dd>the server name (<code><hostname></code>)</dd>
|
||
<dt>port</dt>
|
||
<dd>the server port</dd>
|
||
<dt>user</dt>
|
||
<dd>user as stated in listener HTTP basic auth<br />
|
||
<em>May be blank</em></dd>
|
||
<dt>pass</dt>
|
||
<dd>pass as stated in listener HTTP basic auth
|
||
<em>May be blank</em></dd>
|
||
<dt>client</dt>
|
||
<dd>unique ID for the client within Icecast</dd>
|
||
<dt>ip</dt>
|
||
<dd>listeners IP address</dd>
|
||
<dt>agent</dt>
|
||
<dd>useragent from the listeners player</dd>
|
||
<dt>duration</dt>
|
||
<dd>number of seconds the listener was connected for</dd>
|
||
</dl>
|
||
|
||
<h5 id="example-3">Example</h5>
|
||
<p><code>action=listener_remove&server=icecast.example.org&port=8000&client=1&mount=/live&user=&pass=&duration=3600&ip=127.0.0.1&agent=My%20player</code></p>
|
||
|
||
<h4 id="streamauth">stream_auth</h4>
|
||
<p>Technically this does not belong to listener authentication, but due to its similarity it is explained here too.<br />
|
||
When a source connects, before anything is sent back to them, this request is processed. The default action is to
|
||
reject a source unless the auth server sends back a response header which may be stated in the <code>header</code> option.</p>
|
||
|
||
<h5 id="post-details-4">POST Details</h5>
|
||
<dl>
|
||
<dt>action</dt>
|
||
<dd><code>stream_auth</code></dd>
|
||
<dt>mount</dt>
|
||
<dd>the mountpoint</dd>
|
||
<dt>server</dt>
|
||
<dd>hostname of the Icecast server the client tries to connect to</dd>
|
||
<dt>port</dt>
|
||
<dd>the port of said server</dd>
|
||
<dt>user</dt>
|
||
<dd>username as sent by the source client</dd>
|
||
<dt>pass</dt>
|
||
<dd>password as sent by the source client</dd>
|
||
<dt>admin</dt>
|
||
<dd>admin request (read below)</dd>
|
||
</dl>
|
||
|
||
<p><strong>Note:</strong> As admin requests can come in for a stream (eg. metadata update) these requests can be issued while
|
||
stream is active. For these <code>admin</code> is set to <code>1</code> in POST details.</p>
|
||
|
||
<h5 id="example-4">Example</h5>
|
||
<p><code>action=stream_auth&mount=/stream.ogg&ip=192.0.2.0&server=icecast.example.org&port=8000&user=source&pass=password&admin=1</code></p>
|
||
|
||
<h4 id="other-options">Other Options</h4>
|
||
|
||
<dl>
|
||
<dt>auth_header</dt>
|
||
<dd>The expected response header to be returned that allows the authencation to take place may be specified here.<br />
|
||
The default is:<br />
|
||
<code>icecast-auth-user: 1</code><br />
|
||
but it could be anything you like, for instance:<br />
|
||
<code>HTTP 200 OK</code></dd>
|
||
<dt>timelimit_header</dt>
|
||
<dd>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.</dd>
|
||
<dt>headers</dt>
|
||
<dd>This is a list of HTTP headers provided by the client which should be passed to the authencation service.
|
||
Those headers are prepended by the value of header_prefix and sent as POST parameters.</dd>
|
||
<dt>header_prefix</dt>
|
||
<dd>This is the prefix used for passing client headers. See headers for details.</dd>
|
||
</dl>
|
||
|
||
</div>
|
||
|
||
<div class="article">
|
||
<h3 id="note-player-auth">A note about players and authentication</h3>
|
||
<p>We do not have an exaustive list of players that support listener authentication.<br />
|
||
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 at
|
||
least support the passing of query parameters, other players may also do.</p>
|
||
|
||
</div>
|
||
|
||
<div class="article">
|
||
<h3 id="source-auth">Source Authentication</h3>
|
||
<p>Source authentication is a feature of Icecast which allows you to secure a certain mountpoint such that in order to stream to it,
|
||
a source client must pass some verification test. This section will show you the basics of setting up and maintaining this component.<br />
|
||
To define source authentication, a group of tags are specified in the <code><mount></code> group relating to the mountpoint. </p>
|
||
|
||
<p>The following authentication mechanisms can apply to sources:</p>
|
||
|
||
<ul>
|
||
<li>BASIC: <code><password></code> and possibly <code><username></code> in the <code><mount></code> section</li>
|
||
<li>URL: issue web requests (eg. PHP) to match authentication</li>
|
||
</ul>
|
||
|
||
<h4 id="url-authentication-streamauth">URL authentication: <code>stream_auth</code></h4>
|
||
<p>A <code><mount></code> can contain a section <code><authentication type="url"></code> and therein
|
||
<code><option name="stream_auth" value="http://auth.example.org/source.php"/></code>. When a source connects, before anything is sent back to
|
||
them, this request is processed. The default action is to reject a source unless the auth server sends back a response header which may
|
||
be stated in the <code>header</code> option (same as listener auth). </p>
|
||
|
||
<h5 id="post-details-5">POST Details</h5>
|
||
<dl>
|
||
<dt>action</dt>
|
||
<dd><code>stream_auth</code></dd>
|
||
<dt>mount</dt>
|
||
<dd>the mountpoint</dd>
|
||
<dt>server</dt>
|
||
<dd>hostname of the Icecast server the client tries to connect to</dd>
|
||
<dt>port</dt>
|
||
<dd>the port of said server</dd>
|
||
<dt>user</dt>
|
||
<dd>username as sent by the source client</dd>
|
||
<dt>pass</dt>
|
||
<dd>password as sent by the source client</dd>
|
||
<dt>admin</dt>
|
||
<dd>admin request (read below)</dd>
|
||
</dl>
|
||
|
||
<p><strong>Note:</strong> As admin requests can come in for a stream (eg. metadata update) these requests can be issued while
|
||
stream is active. For these <code>admin</code> is set to <code>1</code> in POST details.</p>
|
||
|
||
<h5 id="example-5">Example</h5>
|
||
<p><code>action=stream_auth&mount=/stream.ogg&ip=192.0.2.0&server=icecast.example.org&port=8000&user=source&pass=password&admin=1</code></p>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
<div class="footer">
|
||
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
|
||
</div>
|
||
|
||
</body>
|
||
</html>
|