Skip to content

GitLab

I
Icecast-Website
Commit bce1614e authored by Marvin Scholz's avatar Marvin Scholz
Browse files
Options

First commit of new Docs, still WIP

parents
Expand all Show whitespace changes
Inline Side-by-side
Showing with 1183 additions and 0 deletions
docs/admin_interface.md 0 → 100644
View file @ bce1614e
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 one mountpoint to another, disconnect connected sources or 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.
# 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.
Example:
`/admin/metadata?mount=/stream&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:
`/admin/fallbacks?mount=/stream.ogg&fallback=/fallback.ogg`
## List Clients
This function lists all the clients currently connected to a specific mountpoint. The results are sent
back in XML form.
Example:
`/admin/listclients?mount=/stream.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:
`/admin/moveclients?mount=/stream.ogg&destination=/newstream.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:
`/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:
`/admin/killsource?mount=/mystream.ogg`
# 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.
Example:
`/admin/stats`
## List Mounts
The list mounts function provides the ability to view all the currently connected mountpoints.
Example:
`/admin/listmounts`
# Web-Based Admin Interface
As an alternative to manually invoking these URLs, there is a web-based admin interface.
This interface provides the same functions that were identified and described above but presents them in
a nicer way. The web-based admin Interface to Icecast is shipped with Icecast provided in the
`admin` directory and comes ready to use.
The main path for the Web-Based Admin Interface is:
`/admin/stats.xsl`
## Advanced
The web-based admin interface is a series of XSL-Transform 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.
__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 the `/web` directory.
These work using the document returned by the `/admin/stats` endpoint.
To see the XML document that is applied to each admin XSLT, just remove the .xsl in your request
(i.e. `/admin/listclients`). You can then code your XSL transform accordingly.
\ No newline at end of file
docs/advanced_config.md 0 → 100644
View file @ bce1614e
This diff is collapsed.
docs/auth.md 0 → 100644
View file @ bce1614e
---
title: Authentication
version: 2.4.99.1
---
{::options auto_ids="true" /}
<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.
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.
The following authentication mechanisms can apply to listeners:
<!-- FIXME -->
* htpasswd: lookup a named file for a matching username and password
* URL: issue web requests (eg. PHP) to match authentication
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.
</div>
<div class="article" markdown="1">
# htpasswd Listener Authentication
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:
<!-- FIXME -->
{% 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.
## 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.png)
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.png)
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”.
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.png)
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">
# URL
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.
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.
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
`Icecast-Auth-Message: Reason`
should also be returned for placing in the log files.
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:
<!-- FIXME -->
{% highlight xml %}
<mount>
<mount-name>/example.ogg</mount-name>
<authentication type="url">
<option name="mount_add" value="http://auth.example.org/stream_start.php"/>
<option name="mount_remove" value="http://auth.example.org/stream_end.php"/>
<option name="listener_add" value="http://auth.example.org/listener_joined.php"/>
<option name="listener_remove" value="http://auth.example.org/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:"/>
<option name="headers" value="x-pragma,x-token"/>
<option name="header_prefix" value="ClientHeader."/>
<option name="stream_auth" value="http://auth.example.org/source.php"/>
</authentication>
</mount>
{% endhighlight %}
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.
<!-- FIXME -->
## mount_add
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.
### POST Details
action
: `mount_add`
mount
: the mountpoint starting up
server
: the server name (`<hostname>`)
port
: the server port
### Example
`action=mount_add&mount=/live&server=icecast.example.org&port=8000`
## mount_remove
This URL is for informing the auth server of a stream finishing, like the start option, no listener details
are passed.
### POST Details
action
: `mount_remove`
mount
: the mountpoint being removed
server
: the server name (`<hostname>`)
port
: the server port
### Example
`action=mount_remove&mount=/live&server=icecast.example.org&port=8000`
## listener_add
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.
### POST Details
action
: `listener_add`
mount
: the mountpoint, including query parameters
server
: the server name (`<hostname>`)
port
: the server port
user
: user as stated in listener HTTP basic auth
_May be blank_
pass
: pass as stated in listener HTTP basic auth
_May be blank_
client
: unique ID for the client within Icecast
ip
: listeners IP address
agent
: useragent from the listeners player
__Note:__ 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.
### Example
`action=listener_add&server=icecast.example.org&port=8000&client=1&mount=/live&user=&pass=&ip=127.0.0.1&agent=My%20player`
## listener_remove
This URL is for when a listener connection closes.
### POST Details
action
: `listener_remove`
mount
: the mountpoint
server
: the server name (`<hostname>`)
port
: the server port
user
: user as stated in listener HTTP basic auth
_May be blank_
pass
: pass as stated in listener HTTP basic auth
_May be blank_
client
: unique ID for the client within Icecast
ip
: listeners IP address
agent
: useragent from the listeners player
duration
: number of seconds the listener was connected for
### Example
`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`
## stream_auth
Technically this does not belong to listener authentication, but due to its similarity it is explained here too.
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 `header` option.
### POST Details
action
: `stream_auth`
mount
: the mountpoint
server
: hostname of the Icecast server the client tries to connect to
port
: the port of said server
user
: username as sent by the source client
pass
: password as sent by the source client
admin
: admin request (read below)
__Note:__ As admin requests can come in for a stream (eg. metadata update) these requests can be issued while
stream is active. For these `admin` is set to `1` in POST details.
### Example
`action=stream_auth&mount=/stream.ogg&ip=192.0.2.0&server=icecast.example.org&port=8000&user=source&pass=password&admin=1`
## Other Options
auth_header
: The expected response header to be returned that allows the authencation to take place may be specified here.
The default is:
`icecast-auth-user: 1`
but it could be anything you like, for instance:
`HTTP 200 OK`
timelimit_header
: 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.
headers
: 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.
header_prefix
: This is the prefix used for passing client headers. See headers for details.
</div>
<div class="article" markdown="1">
# A note about players and authentication
{:#note-player-auth}
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 at
least support the passing of query parameters, other players may also do.
</div>
<div class="article" markdown="1">
# Source Authentication
{:#source-auth}
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.
To define source authentication, a group of tags are specified in the `<mount>` group relating to the mountpoint.
The following authentication mechanisms can apply to sources:
<!-- FIXME -->
* BASIC: `<password>` and possibly `<username>` in the `<mount>` section
* URL: issue web requests (eg. PHP) to match authentication
## URL authentication: `stream_auth`
A `<mount>` can contain a section `<authentication type="url">` and therein
`<option name="stream_auth" value="http://auth.example.org/source.php"/>`. 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 `header` option (same as listener auth).
### POST Details
action
: `stream_auth`
mount
: the mountpoint
server
: hostname of the Icecast server the client tries to connect to
port
: the port of said server
user
: username as sent by the source client
pass
: password as sent by the source client
admin
: admin request (read below)
__Note:__ As admin requests can come in for a stream (eg. metadata update) these requests can be issued while
stream is active. For these `admin` is set to `1` in POST details.
### Example
`action=stream_auth&mount=/stream.ogg&ip=192.0.2.0&server=icecast.example.org&port=8000&user=source&pass=password&admin=1`
</div>
docs/basic_setup.md 0 → 100644
View file @ bce1614e
# Basic Requirements
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.
As already explained in the Introduction, there are two major components involved: The streaming server (Icecast in this case) and the source client.
The following diagram shows how Icecast works:
![Icecast Shema Diagram](img/Icecast_shema.svg)
A Source Client (i.e. IceS, RoarAudio, …) connects to a mountpoint on the Icecast server and sends audio or video data to it. Listeners connect to the mountpoint and Icecast send the stream to them.
The Icecast server will be the place where all listeners of your stream will connect. The source client (in general) runs on a separate machine than Icecast, but does not necessarily need to.
# The Basics
Each Icecast server can house multiple streams, we call these mountpoints. A mountpoint is a unique name on your server identifying a particular stream - it looks like a filename, such as /stream.ogg and a listener can only listen to a single mountpoint at a time. This means you can have a single Icecast server contain 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.
# Setting up Icecast
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.
The first step in the process is to install the Icecast server itself. The recommended way to do this is using the distro packages, or in case of Win32 download the binary package or installer. How to do this is not contained within this documentation.
After installation there is placed a sample config file named `icecast.xml` in either `/usr/local/etc`, `/etc/` or `/etc/icecast2/` (for UNIX) or in the current working directory, in a folder called `etc`, in case you are using the Window binary package.
The next step is to edit the `icecast.xml` config 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:
`<hostname>` - DNS name or IP address used for stream directory listings.
`<source-password>` - Will be used for the source client authentication.
`<admin-password>` - Will be used for authenticating admin features of Icecast.
`<listen-socket>` (both port and bind-address)
If you expect many listeners, make sure to adjust the `<clients>` limit in the `<limits>` block.
Additionally make sure to note where the Icecast log file is stored, see the `<logdir>` value in the `<paths>` section.
Once the configuration file is modified, you should be able to start the server with the following command
icecast -c /path/to/icecast.xml
If no error messages are generated, then check the `error.log` file in the log directory for the ‘server started’ message, it will look something like:
[2014-11-20 19:17:48] INFO main/main Icecast 2.4.1 server started
You may notice slight variations to the line above, but the key thing here is that the server is started, logging is working and the version is shown.
You can also verify that Icecast is started by visiting the following URL [http://localhost:8000/admin/stats.xsl](http://localhost:8000/admin/stats.xsl) on the machine running Icecast. Replace localhost with the correct hostname and adjust the port, if you aren't using the default port 8000.
You should be prompted for a username and password. Enter the username `admin` and the password you entered for `<admin-password>` in the config. If all is well, you should see a Status Page which represents Icecast statistics (more about that later).
# Setting up the Source Client
Now that the Icecast server is started you must configure your source client. The information you will need for the source client is the following:
- Hostname (or IP address) and port of the Icecast server - both of these come from `<listen-socket>`
- Source password - from `<source-password>`
Additionally, you will need to choose a mountpoint and specify this in the source client. Icecast does not need to know about each mountpoint (although you can configure settings for specific mountpoint, this is covered on Advanced configuration), 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).
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.xsl URL that was mentioned above.
Now that you have the source connnected, listening to the stream involves simply opening the appropriate following URL in a browser:
http://yourip:port/mounpoint-you-specified
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` within your media player.
Alternatively you can use `http://192.0.2.23:8000/mystream.ogg.m3u`, (note the .m3u extension added) which will serve up a link that opens most media players. 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.
docs/config_file.md 0 → 100644
View file @ bce1614e
This diff is collapsed.
docs/img/Icecast_shema.svg 0 → 100644
View file @ bce1614e
This source diff could not be displayed because it is too large. You can view the blob instead.
docs/index.md 0 → 100644
View file @ bce1614e
# Icecast 2.4.1 Documentation
Icecast is a streaming media server which currently supports Ogg Vorbis and MP3 audio streams.
It can be used to create an Internet radio station or a privately running jukebox and many
things in between. It is very versatile in that new formats can be added relatively easily
and supports open standards for commuincation and interaction.
Icecast is distributed under the GNU GPL, version 2. A copy of this license is included with
this software in the COPYING file.
There are two major parts to most streaming media servers: The component providing the
content (what we call source clients) and the component which is responsible for serving that
content to listeners (this is the function of Icecast).
# Prerequisites
Icecast requires the following packages:
* [libxml2](http://xmlsoft.org/downloads.html)
* [libxslt](http://xmlsoft.org/XSLT/downloads.html)
* [curl](http://curl.haxx.se/download.html) Version >= 7.10
* [libogg/libvorbis](http://www.vorbis.com/files) Version >= 1.0
* [OpenSSL](https://www.openssl.org/source/) (Optional, enable if SSL support is desired)
# What platforms are supported?
Currently the following Unix platforms are supported:
- Linux (Most flavors including Redhat and Debian)
- FreeBSD
- OpenBSD
- Solaris
Currently the following Windows platforms are supported:
- Windows Vista
- Windows 7
- Windows 8
- Windows Server 2003
- Windows Server 2008
- Windows Server 2012
# Build/Install
To build Icecast on a Unix platform, perform the following:
Run
./configure
make
make install
to build and install this release.
A sample config file will be placed in `/usr/local/etc` (on UNIX) or in the current working
directory (on Win32) and is called `icecast.xml`.
Documentation for Icecast is available in the doc directory, by viewing `doc/index.html` in a
browser.
# Where do I go for questions?
There are many ways to contact the icecast development team, best ways are:
- The [Icecast Mailing list](http://lists.xiph.org/mailman/listinfo/icecast)
- The [Icecast Developer Mailing list](http://lists.xiph.org/mailman/listinfo/icecast-dev), for more development-related questions.
- Icecast IRC Chat at the [#icecast](irc://irc.freenode.net:6667/#icecast) channel on irc.freenode.net
\ No newline at end of file
docs/introduction.md 0 → 100644
View file @ bce1614e
# What is Icecast?
Icecast is a streaming media server which currently supports Ogg Vorbis, Opus, Theora and WebM streams, MP3 and AAC streams are known to work. It can be used to create an Internet radio station or a privately running jukebox and many things in between. It is very versatile in that new formats can be added relatively easily and supports open standards for commuincation and interaction.
There are two major parts to most streaming media servers: the component providing the content (what we call source clients) and the component which is responsible for serving that content to listeners (this is the function of icecast).
# What platforms are supported?
Currently the following Unix platforms are supported:
- Linux (Most flavors including Redhat and Debian)
- FreeBSD
- OpenBSD
- Solaris
Currently the following Windows platforms are supported:
- Windows Vista
- Windows 7
- Windows 8
- Windows Server 2003
- Windows Server 2008
- Windows Server 2012
# Where do I go for questions?
There are many ways to contact the icecast development team
Best Ways:
- Icecast mailing list [http://lists.xiph.org/mailman/listinfo/icecast](http://lists.xiph.org/mailman/listinfo/icecast)
- Icecast Developers mailing list [http://lists.xiph.org/mailman/listinfo/icecast-dev](http://lists.xiph.org/mailman/listinfo/icecast-dev)
- Icecast IRC chat room - irc.freenode.net : #icecast