Commit 2c5ba3bb authored by Marvin Scholz's avatar Marvin Scholz
Browse files

Removed Docs and replaced them with compiled once

This prepares for our switch to mkdocs as docs generator.
parent 2e3d7abd
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs &mdash; Admin Interface</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link type="text/plain" rel="author" href="/humans.txt" />
<link rel="canonical" href="http://icecast.org/docs/icecast-2.0.1/admin-interface.html">
<!-- CSS -->
<link rel="stylesheet" type="text/css" href="/assets/css/style.min.css" media="screen, print" />
</head>
<body>
<div class="header">
<div id="xiphbar">
<h3 class="hidden">Projects by Xiph.Org</h3>
<div>
<a href="http://www.xiph.org/"><img src="/assets/img/xiph-community.svg" alt="the xiph open source community"/></a>
<ul>
<li><a href="http://www.xiph.org/">Xiph.org</a></li>
<li><a href="http://www.opus-codec.org/">Opus</a></li>
<li><a href="http://xiph.org/flac/">FLAC</a></li>
<li><a href="http://www.icecast.org/">Icecast</a></li>
<li><a href="http://www.vorbis.com/">Vorbis</a></li>
<li><a href="http://www.theora.org/">Theora</a></li>
<li><a href="http://www.speex.org/">Speex</a></li>
<li><a href="http://www.xspf.org/">XSPF</a></li>
</ul>
</div>
</div>
<h1><a href="/" title="Home page">Icecast</a> <span>is free server software for streaming multimedia.</span></h1>
<div class="nav">
<h2 class="hidden">Page navigation</h2>
<label for="toggle-nav" title="Toggle navigation"></label>
<input type="checkbox" id="toggle-nav" />
<ul>
<li class="on"><a href="/docs">Docs</a></li>
<li class=""><a href="/download">Download</a></li>
<li class=""><a href="/apps">Apps</a></li>
<li class=""><a href="/ices">IceS</a></li>
<li class=""><a href="http://dir.xiph.org/">Streams</a></li>
<li class=""><a href="/contribute">Contributing</a></li>
<li class=""><a href="/contact">Contact</a></li>
</ul>
</div>
</div>
<div class="section">
<h2>Icecast 2.0.1 Docs &mdash; Admin Interface</h2>
<div class="aside error">
<strong>Please note:</strong> This doc is for an older Icecast version, you can find the latest doc
<a href="/docs/icecast-latest">here</a>.
</div>
<div class="article">
<h3>Overview</h3>
<p>This section contains information about the admin interface of icecast. Through this interface the user can manipulate many server features. From it you can gather statistics, move listeners from mountpoint to mountpoint, disconnect connected sources, disconnect connected listeners, and many other activities. Each function is enumerated here as well as an example usage of the function.</p>
<p>Each of these functions requires HTTP authentication via the appropriate username and password. For mount-specific functions, you may use either the <code>&lt;admin-username&gt;</code> and <code>&lt;admin-password&gt;</code> specified in the icecast config file, or the username and password specified for that mountpoint (if any). For general functions (not specific to a single mountpoint), you must use the admin username and password. It is also important to note that in all the examples 192.168.1.10 is used as the example host and 8000 is used as the example port for the Icecast server.</p>
</div>
<div class="article">
<h3>Admin Functions (mount specific)</h3>
<p>All these admin functions are mount specific in that they only apply to a particular mountpoint
(as opposed to applying to the entire server). Each of these functions requires a mountpoint to
be specified as input.</p>
<h4>Metadata Update</h4>
<p>This function provides the ability for either a source client or any external program to update the metadata information for a particular mountpoint. Currently the only metadata supported is song title and only for MP3 streams.</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/metadata?mount=/mystream&amp;mode=updinfo&amp;song=ACDC+Back+In+Black</code></p>
<h4>Fallback Update</h4>
<p>This function provides the ability for either a source client or any external program to update the
“fallback mountpoint” for a particular mountpoint. Fallback mounts are those that are used in the even
of a source client disconnection. If a source client disconnects for some reason that all currently
connected clients are sent immediately to the fallback mountpoint.</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/fallbacks?mount=/mystream.ogg&amp;fallback=/myfallback.ogg</code></p>
<h4>List Clients</h4>
<p>This function lists all the clients currently connected to a specific mountpoint. The results are sent
back in XML form.</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/listclients?mount=/mystream.ogg</code></p>
<h4>Move Clients (Listeners)</h4>
<p>This function provides the ability to migrate currently connected listeners from one mountpoint to another.
This function requires 2 mountpoints to be passed in: mount (the <em>from</em> mountpoint) and destination
(the <em>to</em> mountpoint). After processing this function all currently connected listeners on mount will
be connected to destination. Note that the destination mountpoint must exist and have a sounce client
already feeding it a stream.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/moveclients?mount=/mystream.ogg&amp;destination=/mynewstream.ogg</code></p>
<h4>Kill Client (Listener)</h4>
<p>This function provides the ability to disconnect a specific listener of a currently connected mountpoint.
Listeners are identified by a unique id that can be retrieved by via the “List Clients” admin function.
This id must be passed in to the request via the variable <code>id</code>. After processing this request, the listener will no longer be
connected to the mountpoint.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/killclient?mount=/mystream.ogg&amp;id=21</code></p>
<h4>Kill Source</h4>
<p>This function will provide the ability to disconnect a specific mountpoint from the server. The mountpoint
to be disconnected is specified via the variable <code>mount</code>.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/killsource?mount=/mystream.ogg</code></p>
</div>
<div class="article">
<h3>Admin Functions (general)</h3>
<h4>Stats</h4>
<p>The stats function provides the ability to query the internal statistics kept by the Icecast server.
Almost all information about the internal workings of the server such as the mountpoints connected,
how many client requests have been served, how many listeners for each mountpoint, etc, are available
via this admin function.<br />
Note that this admin function can also be invoked via the http://server:port/admin/stats.xml syntax,
however this syntax should not be used and will eventually become deprecated!</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/stats</code></p>
<h4>List Mounts</h4>
<p>The list mounts function provides the ability to view all the currently connected mountpoints.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/listmounts</code></p>
</div>
<div class="article">
<h3>Web-Based Admin Interface</h3>
<p>As an alternative to manually invoking these URLs, a web-based admin interface was developed. This
interface provides the same functions that were identified and described above but presents them in
a little nicer way. The web-based admin Interface to Icecast is shipped with Icecast provided in the
<code>admin</code> directory and comes ready to use. All the user needs to do is set the path to this directory
in the config file via the <code>&lt;adminroot&gt;</code> config variable.<br />
The web-based admin interface is a series of XSLT files which are used to display all the XML obtained
via the URL admin interface. This can be changed and modified to suit the user’s need. Knowledge of
XSLT and transformations from XML to HTML are required in order to make changes to these scripts. </p>
<p>The main URL for the Web-Based Admin Interface is:<br />
<code>http://192.168.1.10:8000/admin/stats.xsl</code> </p>
<p>From this URL all of the other admin functions can be exercised.</p>
</div>
</div>
<div class="footer">
<p><a href="https://plus.google.com/100957455777699991449/about">
<img alt="Google+" title="Find uns on Google+" src="/assets/img/google-plus.svg" style="width: 20px;">
</a>
</p>
<p>&copy; 2004-2014 Xiph.Org. All rights reserved.</p>
</div>
</body>
</html>
\ No newline at end of file
---
title: Admin Interface
version: 2.0.1
---
<div class="article" markdown="1">
# Overview
This section contains information about the admin interface of icecast. Through this interface the user can manipulate many server features. From it you can gather statistics, move listeners from mountpoint to mountpoint, disconnect connected sources, disconnect connected listeners, and many other activities. Each function is enumerated here as well as an example usage of the function.
Each of these functions requires HTTP authentication via the appropriate username and password. For mount-specific functions, you may use either the `<admin-username>` and `<admin-password>` specified in the icecast config file, or the username and password specified for that mountpoint (if any). For general functions (not specific to a single mountpoint), you must use the admin username and password. It is also important to note that in all the examples 192.168.1.10 is used as the example host and 8000 is used as the example port for the Icecast server.
</div>
<div class="article" markdown="1">
# Admin Functions (mount specific)
All these admin functions are mount specific in that they only apply to a particular mountpoint
(as opposed to applying to the entire server). Each of these functions requires a mountpoint to
be specified as input.
## Metadata Update
This function provides the ability for either a source client or any external program to update the metadata information for a particular mountpoint. Currently the only metadata supported is song title and only for MP3 streams.
Example:
`http://192.168.1.10:8000/admin/metadata?mount=/mystream&mode=updinfo&song=ACDC+Back+In+Black`
## Fallback Update
This function provides the ability for either a source client or any external program to update the
“fallback mountpoint” for a particular mountpoint. Fallback mounts are those that are used in the even
of a source client disconnection. If a source client disconnects for some reason that all currently
connected clients are sent immediately to the fallback mountpoint.
Example:
`http://192.168.1.10:8000/admin/fallbacks?mount=/mystream.ogg&fallback=/myfallback.ogg`
## List Clients
This function lists all the clients currently connected to a specific mountpoint. The results are sent
back in XML form.
Example:
`http://192.168.1.10:8000/admin/listclients?mount=/mystream.ogg`
## Move Clients (Listeners)
This function provides the ability to migrate currently connected listeners from one mountpoint to another.
This function requires 2 mountpoints to be passed in: mount (the *from* mountpoint) and destination
(the _to_ mountpoint). After processing this function all currently connected listeners on mount will
be connected to destination. Note that the destination mountpoint must exist and have a sounce client
already feeding it a stream.
Example:
`http://192.168.1.10:8000/admin/moveclients?mount=/mystream.ogg&destination=/mynewstream.ogg`
## Kill Client (Listener)
This function provides the ability to disconnect a specific listener of a currently connected mountpoint.
Listeners are identified by a unique id that can be retrieved by via the “List Clients” admin function.
This id must be passed in to the request via the variable `id`. After processing this request, the listener will no longer be
connected to the mountpoint.
Example:
`http://192.168.1.10:8000/admin/killclient?mount=/mystream.ogg&id=21`
## Kill Source
This function will provide the ability to disconnect a specific mountpoint from the server. The mountpoint
to be disconnected is specified via the variable `mount`.
Example:
`http://192.168.1.10:8000/admin/killsource?mount=/mystream.ogg`
</div>
<div class="article" markdown="1">
# Admin Functions (general)
## Stats
The stats function provides the ability to query the internal statistics kept by the Icecast server.
Almost all information about the internal workings of the server such as the mountpoints connected,
how many client requests have been served, how many listeners for each mountpoint, etc, are available
via this admin function.
Note that this admin function can also be invoked via the http://server:port/admin/stats.xml syntax,
however this syntax should not be used and will eventually become deprecated!
Example:
`http://192.168.1.10:8000/admin/stats`
## List Mounts
The list mounts function provides the ability to view all the currently connected mountpoints.
Example:
`http://192.168.1.10:8000/admin/listmounts`
</div>
<div class="article" markdown="1">
# Web-Based Admin Interface
As an alternative to manually invoking these URLs, a web-based admin interface was developed. This
interface provides the same functions that were identified and described above but presents them in
a little nicer way. The web-based admin Interface to Icecast is shipped with Icecast provided in the
`admin` directory and comes ready to use. All the user needs to do is set the path to this directory
in the config file via the `<adminroot>` config variable.
The web-based admin interface is a series of XSLT files which are used to display all the XML obtained
via the URL admin interface. This can be changed and modified to suit the user's need. Knowledge of
XSLT and transformations from XML to HTML are required in order to make changes to these scripts.
The main URL for the Web-Based Admin Interface is:
`http://192.168.1.10:8000/admin/stats.xsl`
From this URL all of the other admin functions can be exercised.
</div>
\ No newline at end of file
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs &mdash; Listener Authentication</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link type="text/plain" rel="author" href="/humans.txt" />
<link rel="canonical" href="http://icecast.org/docs/icecast-2.0.1/auth.html">
<!-- CSS -->
<link rel="stylesheet" type="text/css" href="/assets/css/style.min.css" media="screen, print" />
</head>
<body>
<div class="header">
<div id="xiphbar">
<h3 class="hidden">Projects by Xiph.Org</h3>
<div>
<a href="http://www.xiph.org/"><img src="/assets/img/xiph-community.svg" alt="the xiph open source community"/></a>
<ul>
<li><a href="http://www.xiph.org/">Xiph.org</a></li>
<li><a href="http://www.opus-codec.org/">Opus</a></li>
<li><a href="http://xiph.org/flac/">FLAC</a></li>
<li><a href="http://www.icecast.org/">Icecast</a></li>
<li><a href="http://www.vorbis.com/">Vorbis</a></li>
<li><a href="http://www.theora.org/">Theora</a></li>
<li><a href="http://www.speex.org/">Speex</a></li>
<li><a href="http://www.xspf.org/">XSPF</a></li>
</ul>
</div>
</div>
<h1><a href="/" title="Home page">Icecast</a> <span>is free server software for streaming multimedia.</span></h1>
<div class="nav">
<h2 class="hidden">Page navigation</h2>
<label for="toggle-nav" title="Toggle navigation"></label>
<input type="checkbox" id="toggle-nav" />
<ul>
<li class="on"><a href="/docs">Docs</a></li>
<li class=""><a href="/download">Download</a></li>
<li class=""><a href="/apps">Apps</a></li>
<li class=""><a href="/ices">IceS</a></li>
<li class=""><a href="http://dir.xiph.org/">Streams</a></li>
<li class=""><a href="/contribute">Contributing</a></li>
<li class=""><a href="/contact">Contact</a></li>
</ul>
</div>
</div>
<div class="section">
<h2>Icecast 2.1.0 Docs &mdash; Listener Authentication</h2>
<div class="aside error">
<strong>Please note:</strong> This doc is for an older Icecast version, you can find the latest doc
<a href="/docs/icecast-latest">here</a>.
</div>
<div class="article">
<h3>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>
</div>
<div class="article">
<h3>htpasswd Listener Authentication</h3>
<h4>Config File Entries</h4>
<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>&lt;mount&gt;</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">&lt;mount&gt;</span>
<span class="nt">&lt;mount-name&gt;</span>/example.ogg<span class="nt">&lt;/mount-name&gt;</span>
<span class="nt">&lt;authentication</span> <span class="na">type=</span><span class="s">&quot;htpasswd&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;filename&quot;</span> <span class="na">value=</span><span class="s">&quot;myauth&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;allow_duplicate_users&quot;</span> <span class="na">value=</span><span class="s">&quot;0&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/authentication&gt;</span>
<span class="nt">&lt;/mount&gt;</span></code></pre></div>
<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 />
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. Only mounts that are named in the config file can be configured for listener authentication.</p>
<h4>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.jpg" 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.jpg" 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 New User”.<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>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.jpg" 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>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.</p>
</div>
</div>
<div class="footer">
<p><a href="https://plus.google.com/100957455777699991449/about">
<img alt="Google+" title="Find uns on Google+" src="/assets/img/google-plus.svg" style="width: 20px;">
</a>
</p>
<p>&copy; 2004-2014 Xiph.Org. All rights reserved.</p>
</div>
</body>
</html>
\ No newline at end of file
---
title: Listener Authentication
version: 2.1.0
---
<div class="article" markdown="1">
# Listener Authentication
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.
</div>
<div class="article" markdown="1">
# htpasswd Listener Authentication
## Config File Entries
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:
{% highlight xml %}
<mount>
<mount-name>/example.ogg</mount-name>
<authentication type="htpasswd">
<option name="filename" value="myauth"/>
<option name="allow_duplicate_users" value="0"/>
</authentication>
</mount>
{% endhighlight %}
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 Icecast authenticator to use.
Currently, only `htpasswd` and `url` are implemented. 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.
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.
## Configuring Users and Passwords
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:
![Screenshot of Admin Stats](img/listener_auth1.jpg)
You will see a lock in front of all mountpoint configured for listener authentication. Also note that this page will
only show _connected_ mountpoints.
To manage users and passwords for this mountpoint, click on the “Manage Authentication” link. The following screen will be shown:
![Screenshot of Manage Authentication](img/listener_auth2.jpg)
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.
## Finishing it all off
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.
![Screenshot of Auth Page](img/listener_auth3.jpg)
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.
</div>
<div class="article" markdown="1">
# A note about players and authentication
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.
</div>
\ No newline at end of file
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs &mdash; Basic Setup</title>