Commit abc75687 authored by ePirat's avatar ePirat

Docs: 2.4.1 docs added

svn path=/icecast/trunk/icecast/; revision=19319
parent e7d68fd3
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1">
<!-- Sitemap 1.0 -->
</HEAD><BODY>
<UL>
</UL>
</BODY></HTML>
This diff is collapsed.
This diff is collapsed.
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Admin Interface</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.1 Docs &mdash; Admin Interface</h2>
<div class="article">
<h3 id="overview">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 id="admin-functions-mount-specific">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 id="metadata-update">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.</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 id="fallback-update">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 id="list-clients">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 id="move-clients-listeners">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 id="kill-client-listener">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 id="kill-source">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 id="admin-functions-general">Admin Functions (general)</h3>
<h4 id="stats">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 id="list-mounts">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 id="web-based-admin-interface">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.
<strong>Modification of existing XSLT transforms in <code>/admin</code> is allowed, but new files cannot be created here</strong>.
Creation of new XSLT transforms as well as modification of existing transforms is allowed in <code>/web</code>.
These work using the document returned by <code>/admin/stats.xml</code>.<br />
To see the XML document that is applied to each admin XSLT, just remove the <code>.xsl</code> in your request
(i.e. <code>/admin/listclients</code>). You can then code your XSLT transform accordingly.</p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>
\ No newline at end of file
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Basic Setup</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.1 Docs &mdash; Basic Setup</h2>
<div class="article">
<h3 id="basic-requirements">Basic Requirements</h3>
<p>This section will describe the essential requirements in setting up a simple Internet radio station. It is by no means a complete list but should give you enough to get started. Please also note that those are generic instructions. If you installed a Linux/Unix distribution package, then it will likely come with different paths, different means of starting it, etc. In that case please also refer to the documentation of that distribution and or a distribution specific How-To.</p>
<p>There are two major components involved: the streaming server (Icecast in this case) and the source client.<br />
The Icecast server will be the place where all listeners of your station will connect. The source client (in general) runs on a separate machine than Icecast, but does not necessarily need to. Source clients send the content to Icecast and provide the stream data (encoded audio) that is then relayed out to listeners by Icecast.</p>
<p>It is important to note that not all source clients work with Icecast 2. You will need to check to make sure that Icecast 2 is supported by your chosen source client.</p>
</div>
<div class="article">
<h3 id="the-basics">The Basics</h3>
<p>Each Icecast server can house multiple broadcasts (or mountpoints) each containing a separate stream of content. A ‘mountpoint’ is a unique name on your server identifying a particular stream - it looks like a filename, such as ‘/stream.ogg’. A listener can only listen to a single mountpoint at a time. This means you can have a single Icecast server contain either multiple broadcasts with different content, or possibly the same broadcast but with streams of different bitrates or qualities. In this case each broadcast or stream is a separate mountpoint.</p>
<p>At this point, the steps outlined here related to the Unix version or Win32 console version of Icecast. Icecast is also available in a Win32 GUI version, and the steps are similar in setup, but not quite the same.</p>
<p>The first step in the process is to find and install the Icecast2 server itself. How to do this is not contained within this documentation. After installation you should have and Icecast binary and 3 directories</p>
<ul>
<li><code>conf</code><br />
Contains the Icecast configuration file (<code>icecast.xml</code>) which defines all the configuration parameters for the server. </li>
<li><code>admin</code><br />
Contains xslt files which are used by the Icecast server to provide a web-based front end to the administration capabilities of the server. </li>
<li><code>logs</code><br />
This is a blank directory which (if specified in the config file) will contain all the logs (there are 2) for Icecast. </li>
</ul>
<p>The next step is to edit the <code>icecast.xml</code> file and set the appropriate values. Most of the specified values in the samples are fine, for a basic setup the following entries should be specified, and if neccessary, changed to suite your situation:</p>
<p><code>&lt;hostname&gt;</code> - DNS name or IP address used for stream directory listings.<br />
<code>&lt;source-password&gt;</code> - Will be used for the source client authentication.<br />
<code>&lt;admin-password&gt;</code> - Will be used for authenticating admin features of Icecast.<br />
<code>&lt;listen-socket&gt;</code> (both port and bind-address) </p>
<p>Once the configuration file is modified, you should be able to start the server with the following command</p>
<pre><code>icecast -c /path/to/icecast.xml
</code></pre>
<p>If no error messages are generated, then check the <code>error.log</code> file for the ‘server started’ message, it will look something like :</p>
<pre><code>[2003-10-31 13:04:49] INFO main/main.c Icecast 2.3.0 server started
</code></pre>
<p>You may notice slight variations to the line above, the time will no doubt be different, and on some platforms the <code>main.c</code> is just main, but the key thing here is that the server is started, logging is working and the version is shown. </p>
<p>You can also verify that it started by visiting the following URL: <code>http://yourip:port/admin/stats.xml</code>. You should be prompted for a username and password. Enter the username <code>admin</code> and the password you entered for <code>&lt;admin-password&gt;</code>. If all is well, you should see an small XML tree which represents Icecast statistics (more about that later). </p>
<p>Now that the Icecast server is started you must now configure your source client. The information you will need for the source client is the following: </p>
<p>IP address and Port of the icecast server - both of these come from <code>&lt;listen-socket&gt;</code><br />
source password - from <code>&lt;source-password&gt;</code> </p>
<p>Additionally, you will need to choose a mountpoint and specify this in the source client. Icecast does not need to know about each mount point (although you can configure settings for specific mountpoint - this is covered under Advanced configuration) there are, however, some points to mention regarding mountpoints. All Ogg Vorbis streams should have mountpoints that end in <code>.ogg</code> (i,e. <code>/mystream.ogg</code>). This is due to the lazy way most media players infer the type of stream. MP3 streams usually do not contain an extension (/mystream). Mount points also should not contain any spaces or odd characters (again due to the lazy way many of the media players are coded). </p>
<p>Once you have configured your source client, you should be able to connect it to the Icecast server. Verify that it is connected by hitting the stats.xml URL that was mentioned above. </p>
<p>Now that you have the source connnected, listening to the stream involves simply opening the appropriate following URL in a browser: <code>http://yourip:port/mounpoint-you-specified</code>. So, for instance, if you attached your source client to an icecast server located at <code>192.0.2.23:8000</code> with a mountpoint of <code>/mystream.ogg</code>, then you would open: <code>http://192.0.2.23:8000/mystream.ogg</code> or <code>http://192.0.2.23:8000/mystream.ogg.m3u</code>. Note that the URL with <code>.m3u</code> extention will serve up a link that opens most media players. Also it is important to note that m3u need not contain only MP3 stream, it can contain streams of arbitrary content-type and is used by Icecast to serve a playlist that represents your broadcast to listening clients. Alternatively you can open up the stream URL directly within your media player (<code>http://192.0.2.23:8000/mystream.ogg</code> in this case)</p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>
\ No newline at end of file
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Changes</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.1 Docs &mdash; Changes</h2>
<div id="v2.4.1" class="article">
<h3 id="version-241">Version 2.4.1</h3>
<h4 id="fixes">Fixes</h4>
<ul>
<li>Fixed cross-corruption of file descriptors by on-connect/on-disconnect scripts, specifically STDIN, STDOUT and STDERRR vs TCP connections.
<ul>
<li>We actually close not just 0, 1 and 2, but the first 1024 FDs, which seems common trade-off practice, but still not ideal. A more thorough fix will need platform specific logic and significant work.</li>
<li>The STDIN/OUT/ERR problem is fixed reliably, but other problems could occur if both the script and the server use FDs &gt;1024 at the same time</li>
<li>This is now reasonably safe, but care should be exercised nevertheless. </li>
</ul>
</li>
<li>Disabled SSLv3 and SSL compression explicitly to improve security</li>
<li>Updated the default ciphers to be more secure</li>
<li>Fixed JSON status API problems
<ul>
<li>Put the XSLT last item check into every filtered tag.</li>
<li>This way we shouldn’t run into problems of this type anymore.</li>
<li>Also it should be easier to customize the XSLT this way, if someone wants to filter differently.</li>
</ul>
</li>
<li>Fixed <code>&lt;auth&gt;</code> in <code>&lt;mount type="default"&gt;</code> to work properly.</li>
<li>Fixed listener connection duration logging in access.log. Regression was introduced for only some platforms by an earlier security fix.</li>
<li>Fixed time zone reporting in _iso8601 fields on Windows.</li>
<li>added warnings on empty and default values of <code>&lt;fileserve&gt;</code>, <code>&lt;hostname&gt;</code>, <code>&lt;location&gt;</code>, <code>&lt;admin&gt;</code> and <code>&lt;server-id&gt;</code></li>
<li>send errorlog (loglevel WARN) to stderr prior to opening logfiles.</li>
<li>Fixed handling of empty strings in config file. Now empty strings are handled in: accesslog, errorlog, logdir, webroot, adminroot and hopefully all kinds of port.</li>
<li>Be more verbose in case of fileserve off. People disable fileserve and then wonder why the web interface CSS breaks.</li>
<li>More details in log messages
<ul>
<li>Add source IP adress to startup and source exit logging</li>
<li>Add mountpoint to some log lines</li>
</ul>
</li>
<li>Updated the config file to avoid common pitfalls and make some things more obvious.</li>
<li>Fixed some compiler warnings</li>
<li>Fixed autogen.sh to work properly on Mac OS</li>
<li>Fixed JSON access by adding support for global and mount specific custom HTTP headers.
<ul>
<li>The purpose is to fix JSON access from browsers, by supporting basic CORS use cases. This is both important for some HTML5 <code>&lt;audio&gt;</code> or <code>&lt;video&gt;</code> use cases and accessing the JSON status API.</li>
<li>The default icecast config contains the very permissive global header: &lt;header name="Access-Control-Allow-Origin" value="*" /&gt;</li>
</ul>
</li>
</ul>
<h4 id="known-issues">Known issues</h4>
<ul>
<li>HTTP PUT implementation currently doesn’t support chunked encoding yet.</li>
<li>HTTP PUT with “Expect: 100-Continue” receives first a “100” and soon after a “200”, instead of the “200” at the end of transmission.</li>
<li>Caution should be exercised when using <code>&lt;on-connect&gt;</code> or <code>&lt;on-disconnect&gt;</code>, as there is a small chance of stream file descriptors being mixed up with script file descriptors, if the FD numbers go above 1024. This will be further addressed in the next Icecast release.</li>
<li>Don’t use comments inside <code>&lt;http-headers&gt;</code> as it will prevent processing of further <code>&lt;header&gt;</code> tags.</li>
</ul>
</div>
<div id="v2.4.0" class="article">
<h3 id="version-240">Version 2.4.0</h3>
<h4 id="new-features">New Features</h4>
<ul>
<li>Support for Ogg Opus streams</li>
<li>Support for WebM streams</li>
<li>HTTP 1.1 PUT support for source connections. Deprecating SOURCE method</li>
<li><em>Default mount</em><br />
This allows you to define a global set of defaults for ALL mounts. This way you can use e.g. url-auth for sources and or listeners also for dynamically generated mounts.</li>
<li><em>Web interface redone</em>
<ul>
<li>Web output properly redone, credit to ePirat</li>
<li>Added <code>&lt;audio&gt;</code> element for supported audio streams</li>
<li>Now validates completely as XHTML1.0 strict</li>
<li>Also improves rendering on mobile devices</li>
</ul>
</li>
<li>Added basic JSON API (<code>/status-json.xsl</code>) based on a xml2json template by Doeke Zanstra (see <code>xml2json.xslt</code>). Output is roughly limited to data also visible through <code>status.xsl</code></li>
<li>Send charset in HTTP headers for everything, excluding file-serv and streams</li>
<li>Allow (standard strftime(3)) <code>%x</code> codes in <code>&lt;dump-file&gt;</code>. Disabled for Win32</li>
<li>Added <code>stream_start_iso8601</code>, <code>server_start_iso8601</code> to statitics. ISO8601 compliante timestamps for statistics. Should make usage in e.g. JSON much easier. Added as new variables to avoid breaking backwards compatibility</li>
<li>Now compiles for Win32 using mingw</li>
<li>Added options <code>headers</code> and <code>header_prefix</code> to URL based listener auth</li>
<li>Updated <code>listener_remove</code> handler, added <code>ip=</code> and <code>agent=</code></li>
<li>Allow full URLs to be returned by the master server</li>
</ul>
<h4 id="fixes-1">Fixes</h4>
<ul>
<li><strong>Security fix</strong>: Override supplementary groups if is used</li>
<li>Fixes for some race conditions</li>
<li>Dropped debian packaging directory as debian use their own.</li>
<li>Send proper HTTP headers in responses to clients.</li>
<li>Corrected Content-Length: header in admin (raw) requests. Thanks to paluh for reporting.</li>
<li>Escape log entries in access log</li>
<li>Fixed a memory leak. Lost headers of stream because of wrong ref counter in associated refbuf objects.</li>
<li>Avoid memory leak in <code>_parse_mount()</code> when <code>type</code>-attribute is set</li>
<li>Updated web interface to be XHTML compliant.</li>
<li>Removed <code>status2.xsl</code> from release. It was only a broken example file anyway.</li>
</ul>
<h4 id="known-issues-1">Known issues</h4>
<ul>
<li>Will crash if certain config tags are left empty</li>
</ul>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>
\ No newline at end of file
This diff is collapsed.
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; FAQ</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.1 Docs &mdash; FAQ</h2>
<div class="article">
<h3 id="general-questions">General Questions</h3>
<h4 id="what-is-icecastorg">What is Icecast.org?</h4>
<p>Icecast.org, the project, is a collection of programs and libraries for streaming audio over the Internet. This includes:
* Icecast, a program that streams audio data to listeners
* libshout, a library for communicating with Icecast servers
* IceS, a program that sends audio data to Icecast servers</p>
<p>A source client is an external program which is responsible for sending content data to Icecast. Some source clients that
support Icecast 2 are Oddcast, Ices 2, Ices 0.3, and DarkIce.</p>
<h4 id="what-is-icecast-the-program">What is Icecast, the program?</h4>
<p>Icecast streams audio to listeners, and is compatible with Nullsoft’s Shoutcast.</p>
<h4 id="what-is-libshout">What is libshout?</h4>
<p>libshout is a library for communicating with and sending data to an Icecast server. It handles the socket connection,
the timing of the data, and prevents bad data from getting to the Icecast server.</p>
<h4 id="what-is-ices">What is Ices?</h4>
<p>Ices is a program (source client) that sends audio data to an Icecast server to broadcast to clients.<br />
Ices can either read audio data from disk, such as from Ogg Vorbis files, or sample live audio from a sound card and encode
it on the fly.</p>
<h4 id="what-can-i-use-to-listen-to-an-icecast-stream">What can I use to listen to an Icecast stream?</h4>
<p>We maintain a list of Icecast-compatible audio players at <a href="http://www.icecast.org/">icecast.org</a>.</p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>
\ No newline at end of file
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Glossary</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.1 Docs &mdash; Glossary</h2>
<div class="article">
<dl>
<dt>Source client</dt>
<dd>A source client is an external program which is responsible for sending content data to Icecast.<br />
Some source clients that support Icecast 2 are Oddcast, Ices 2, Ices 0.3 and DarkIce.</dd>
<dt>Slave server (Relay)</dt>
<dd>The slave server in a relay configuration is the server that is pulling the data from the master server.
It acts as a listening client to the master server.</dd>
<dt>Master server (Relay)</dt>
<dd>The master server in a relay configuration is the server that has the stream that is being relayed.</dd>
<dt>Mountpoint</dt>
<dd>A mountpoint is a resource on the Icecast server that represents a single broadcast stream. Mountpoints are
named similar to files (<code>/mystream.ogg</code>, <code>/mymp3stream</code>).<br />
When listeners connect to Icecast, they must specify the mountpoint in the request (i.e. <code>http://192.168.1.10:8000/mystream.ogg</code>).
Additionally, source clients must specify a mountpoint when they connect as well. Statistics are kept track of by mountpoint.
Mountpoints are a fundamental aspect of Icecast 2 and how it is organized.</dd>
<dt>Fallback mountpoint</dt>
<dd>A fallback mountpoint is configured with a parent mountpoint. In the event of the parent mountpoint losing connection with Icecast,
Icecast will then move all clients currently connected to the now defunct mountpoint to it’s fallback mountpoint.</dd>
</dl>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>
\ No newline at end of file
<?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 Admin Interface</h1>
<hr id='titlebar' />
<br />
<br />
<br />
<h2>Overview</h2>
<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 &lt;admin-username&gt; and &lt;admin-password&gt; 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>
<br />
<br />
<br />
<h2>Admin Functions (mount specific)</h2>
<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>
<h3>Metadata Update</h3>
<h4>description</h4>
<div class="indentedbox">
This function provides the ability for either a source client or any external program to update the metadata information for a particular mountpoint.
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/metadata?mount=/mystream&amp;mode=updinfo&amp;song=ACDC+Back+In+Black
</pre>
<br />
<br />
<h3>Fallback Update</h3>
<h4>description</h4>
<div class="indentedbox">
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.
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/fallbacks?mount=/mystream.ogg&amp;fallback=/myfallback.ogg
</pre>
<br />
<br />
<h3>List Clients</h3>
<h4>description</h4>
<div class="indentedbox">
This function lists all the clients currently connected to a specific mountpoint. The results are sent back in XML form.
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/listclients?mount=/mystream.ogg
</pre>
<br />
<br />
<h3>Move Clients (Listeners)</h3>
<h4>description</h4>
<div class="indentedbox">
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.
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/moveclients?mount=/mystream.ogg&amp;destination=/mynewstream.ogg
</pre>
<br />
<br />
<h3>Kill Client (Listener)</h3>
<h4>description</h4>
<div class="indentedbox">
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. After processing this request, the listener will no longer be connected to the mountpoint.
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/killclient?mount=/mystream.ogg&amp;id=21
</pre>
<br />
<br />
<h3>Kill Source</h3>
<h4>description</h4>
<div class="indentedbox">
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".
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/killsource?mount=/mystream.ogg
</pre>
<br />
<br />
<br />
<h2>Admin Functions (general)</h2>
<h3>Stats</h3>
<h4>description</h4>
<div class="indentedbox">
This admin 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.
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/stats
</pre>
<br />
<br />
<h3>List Mounts</h3>
<h4>description</h4>
<div class="indentedbox">
This admin function provides the ability to view all the currently connected mountpoints.
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/listmounts
</pre>
<br />
<br />
<br />
<h2>Web-Based Admin Interface</h2>
<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 "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 &lt;adminroot&gt; config variable.</p>
<p>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</p>
<pre>
http://192.168.1.10:8000/admin/stats.xsl
</pre>
<p>From this URL all of the other admin functions can be exercised.</p>
<p>Modification of existing XSLT transforms in /admin is allowed, but new files cannot be created here. Creation of new XSLT transforms as well as modification of existing transforms is allowed in /web. These work using the document returned by /admin/stats.xml. To see the XML document that is applied to each admin XSLT, just change the .xsl to .xml in your request (i.e. /admin/listclients.xml). You can then code your XSLT transform accordingly.
</p>
</div>
</body>
</html>
This diff is collapsed.
<?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 Basic Setup</h1>
<hr id='titlebar' />
<p>
<br />
<br />
<br />
</p>
<h2>Basic Requirements</h2>
<p>This section will describe the essential requirements in setting up a simple Internet radio station. It is by no means a complete list but should give you enough to get started. Please also note that those are generic instructions. If you installed a Linux/Unix distribution package, then it will likely come with different paths, different means of starting it, etc. In that case please also refer to the documentation of that distribution and or a distribution specific HowTo.</p>
<p>There are two major components involved: the streaming server (icecast in this case) and the source client. The icecast server will be the place where all listeners of your station will connect. The source client (in general) runs on a separate machine than icecast, but does not necessarily need to. Source clients send the content to icecast and provide the stream data (encoded audio) that is then relayed out to listeners by icecast.</p>
<p>It is important to note that not all source clients work with icecast2. You will need to check to make sure that icecast2 is supported by your chosen source client.</p>
<p>
<br />
<br />
<br />
</p>
<h2>The Basics</h2>
<p>Each icecast server can house multiple broadcasts (or mountpoints) each containing a separate stream of content. A 'mountpoint' is a unique name on your server identifying a particular stream - it looks like a filename, such as '/stream.ogg'. A listener can only listen to a single mountpoint at a time. This means you can have a single icecast server contain either multiple broadcasts with different content, or possibly the same broadcast but with streams of different bitrates or qualities. In this case each broadcast or stream is a separate mountpoint.</p>
<p>At this point, the steps outlined here related to the Unix version or Win32 console version of icecast. Icecast is also available in a Win32 GUI version, and the steps are similar in setup, but not quite the same.</p>
<p>The first step in the process is to find and install the icecast2 server itself. How to do this is not contained within this documentation. After installation you should have and icecast binary and 3 directories</p>
<div style="text-align:center;">
<table border="1" width="75%">
<tr><td>conf</td><td>Contains the icecast configuration file (icecast.xml) which defines all the configuration parameters for the server.</td></tr>
<tr><td>admin</td><td>Contains xslt files which are used by the icecast server to provide a web-based front end to the administration capabilities of the server.</td></tr>
<tr><td>logs</td><td>This is a blank directory which (if specified in the config file) will contain all the logs (there are 2) for icecast.</td></tr>
</table>
</div>
<p>The next step is to edit the icecast.xml file and set the appropriate values. Most of the
specified values in the samples are fine, for a basic setup the following entries should be
specified, and if neccessary, changed to suite your situation :
<br /><br />
</p>
<pre>
&lt;hostname&gt; - DNS name or IP address used for stream directory listings.
&lt;source-password&gt; - will be used for the source client authentication
&lt;admin-password&gt; - will be used for authenticating admin features of icecast
&lt;listen-socket&gt; (both port and bind-address)
</pre>
<p>Once the configuration file is modified, you should be able to start the server with the following command</p>
<pre>
icecast -c /path/to/icecast.xml
</pre>
<p>If no error messages are generated, then check the error.log file for the 'server started'
message, it will look something like :-</p>
<pre>
[2003-10-31 13:04:49] INFO main/main.c Icecast 2.3.0 server started
</pre>
<p>You may notice slight variations to the line above, the time will no doubt be different,
and on some platforms the main.c is just main, but the key thing here is that the server is
started, logging is working and the version is shown.
</p>
<p>You can also verify that it started by visiting the following URL : http://yourip:port/admin/stats.xml. You should be prompted for a username and password. Enter the username "admin" and the password you entered for &lt;admin-password&gt;. If all is well, you should see an small XML tree which represents icecast statistics (more about that later).</p>
<p>Now that the icecast server is started you must now configure your source client. The information you will need for the source client is the following : <br />
<br />
IP address and Port of the icecast server - both of these come from &lt;listen-socket&gt;<br />
source password - from &lt;source-password&gt;
</p>
<p>Additionally, you will need to choose a mountpoint and specify this in the source client. Icecast does not need to know about each mount point (although you can configure settings for specific mountpoint - this is covered under Advanced configuration) there are, however, some points to mention regarding mountpoints. All Ogg Vorbis streams should have mountpoints that end in .ogg (i,e. /mystream.ogg). This is due to the lazy way most media players infer the type of stream. MP3 streams usually do not contain an extension (/mystream). Mount points also should not contain any spaces or odd characters (again due to the lazy way many of the media players are coded).</p>
<p>Once you have configured your source client, you should be able to connect it to the icecast server. Verify that it is connected by hitting the stats.xml URL that was mentioned above.</p>
<p>Now that you have the source connnected, listening to the stream involves simply opening the appropriate following URL in a browser: http://yourip:port/mounpointyouspecified . So, for instance, if you attached your source client to an icecast server located at 192.0.2.23:8000 with a mountpoint of /mystream.ogg, then you would open : http://192.0.2.23:8000/mystream.ogg or http://192.0.2.23:8000/mystream.ogg.m3u. Note that the URL with .m3u extention will serve up a link that opens most media players. Also it is important to note that m3u need not contain only MP3 stream, it can contain streams of arbitrary content-type and is used by icecast to serve a playlist that represents your broadcast to listening clients. Alternatively you can open up the stream URL directly within your media player (http://192.0.2.23:8000/mystream.ogg in this case)</p>
<p>
<br />
<br />
<br />
</p>
</div>
</body>
</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>