Commit bce1614e authored by Marvin Scholz's avatar Marvin Scholz

First commit of new Docs, still WIP

parents
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
This diff is collapsed.
This diff is collapsed.
# 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.
This diff is collapsed.
This source diff could not be displayed because it is too large. You can view the blob instead.
# 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
# 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
Relaying is the process by which one server mirrors one or more streams from a remote server. The servers
need not be of the same type (i.e. Icecast can relay from Shoutcast). Relaying is used primarily for large
broadcasts that need to distribute listening clients across multiple physical machines.
# Type of Relays
There are two types of relays that Icecast supports:
The first type is when both master and slave servers are Icecast 2 servers. In this case, a “master-slave” relay
can be setup such that all that needs to be done is configure the slave server with the connection information
(server IP and port) of the master server and the slave will mirror all mountpoints on the master server. The slave
will also periodically check the master server to see if any new mountpoints have attached and if so will relay those
as well.
The second type of relay is a specific mountpoint relay. In this case, the slave server is configured with a
server IP, port and mountpoint and only the mountpoint specified is relayed.
# Setting Up a Master-Slave Relay
In order to setup a relay of this type both servers (the one you wish to relay and the one doing the relaying)
need to be Icecast 2 servers.
The following configuration snippet is used as an example:
```xml
<master-server>192.168.1.11</master-server>
<master-server-port>8001</master-server-port>
<master-update-interval>120</master-update-interval>
<master-username>relay</master-username>
<master-password>hackme</master-password>
<relays-on-demand>0</relays-on-demand>
```
In this example, this configuration is setup in the server which will be doing the relaying (slave server).
The master server in this case need not be configured (and actually is unaware of the relaying being performed).
When the slave server is started, it will connect to the master server, 192.168.1.11:8001 in this example. The slave server will begin to relay all non-hidden mountpoints connected to the master server. Additionally, every master-update-interval, 120 seconds
in this case, the slave server will poll the master server to see if any new mountpoints have connected.
Note that the names of the mountpoints on the slave server will be identical to those on the master server.
Configuration options:
master-server
: This is the hostname (or IP) for the server which contains the mountpoints to be relayed (Master Server).
master-server-port
: This is the TCP port for the server which contains the mountpoints to be relayed (Master Server).
master-update-interval
: The interval in seconds that the relay server will poll the master server for any new mountpoints to relay.
master-username
: This is the relay username for the master server, used to query the server for a list of mountpoints to relay.
(Defaults to `relay`)
master-password
: This is the relay password for the master server, used to query the server for a list of mounpoints to relay.
relays-on-demand
: Global on-demand setting for relays. Because you do not have individual relay options when using a master server relay, you still may want those relays to only pull the stream when there is at least one listener on the slave. The typical case here is to avoid bandwidth costs when no one is listening.
# Specific Mountpoint Relay
If only specific mountpoints need to be relayed, or the master server is not a Icecast 2 server, you can use the specific
mountpoint relay. Supported master servers for this type of relay are Shoutcast, Icecast 1.x, and of course Icecast 2.
The following configuration snippet is used as an example:
```xml
<relay>
<server>192.168.1.11</server>
<port>8001</port>
<mount>/example.ogg</mount>
<local-mount>/different.ogg</local-mount>
<username>Jekyll</username>
<password>Hyde</password>
<relay-shoutcast-metadata>0</relay-shoutcast-metadata>
<on-demand>1</on-demand>
</relay>
```
In this example, this configuration is setup in the server which will be doing the relaying (slave server).
The master server in this case need not be configured (and actually is unaware of the relaying being performed) as a
relay. When the slave server is started, it will connect to the master server, in this example located at 192.168.1.11:8001
and will begin to relay only the mountpoint specified (/example.ogg in this case).
Using this type of relay, the user can override the local mountpoint name and make it something entirely different than the one on the master server. Additionally, if the server is a Shoutcast server, then the `<mount>` must be specified as `/`,
and if you want the Shoutcast relay stream to have metadata contained within it (Shoutcast metadata is embedded
in the stream itself), the `<relay-shoutcast-metadata>` needs to be set to `1`.
Configuration options:
server
: This is the hostname (or IP) for the server which contains the mountpoint to be relayed.
port
: This is the TCP port for the server which contains the mountpoint to be relayed.
mount
: The mountpoint located on the remote server. (If you are relaying a Shoutcast stream, this should be `/`)
local-mount
: The name to use for the local mountpoint. This is what the mountpoint will be called on the relaying server. (Defaults to the remote mountpoint)
username
: The username, if required, for the remote mountpoint.
password
: The password, if required, for the remote mountpoint.
relay-shoutcast-metadata
: If relaying a Shoutcast stream, set this to `1` to relay the metadata (song titles), which are part of the Shoutcast data stream. (Defaults to enabled, but it's up to the remote server if metadata is sent)
Possible values: `1`: enabled, `0`: disabled
on-demand
: An on-demand relay will only retrieve the stream if there are listeners requesting the stream. (Defaults to the value of `<relays-on-demand>`)
Possible values: `1`: enabled, `0`: disabled
\ No newline at end of file
Icecast provides extensive run time statistics. Both in the form of active connection numbers and cumulative
counters (since server startup or respectively source connection startup).
# HTML Interface
Icecast comes with a HTML web interface, it exposes a basic set of server statistics that should
fulfil basic user needs. Icecast uses the very powerful libxslt engine to transform its internal
raw statistical data into custom tailored interfaces.
Many people have written custom XSLT code that produces e.g. plain text “now playing”, XSPF, VCLT,
munin interface data, etc. If so desired, the files in webroot can be customized to contain more or less
information (see section on raw XML data below).
!!! attention
__We strongly discourage attempts to scrape data from the web interface__ as we do not consider this an
API and will change it, even completely, between versions! The preferred ways are custom XSLT, JSON and raw XML.
# JSON Stats
Since version 2.4.0 Icecast includes a basic JSON endpoint (`/status-json.xsl`) based on a xml2json template by Doeke Zanstra
(see `xml2json.xslt`). It exposes the same set of server statistics that are available through the web interface and
should fulfil basic user needs. The intention is to not break backwards compatibility of this interface in the future,
still we recommend to design robust software that can deal with possible changes like addition or removal of variables.
Also note that not all variables are available all the time and availability may change at runtime due to stream type, etc.
# Available XML data
This section contains information about the raw XML server statistics data available inside Icecast. An example
stats XML tree will be shown and each element will be described. The following example stats tree will be used:
```xml
<icestats>
<admin>icemaster@localhost</admin>
<client_connections>649</client_connections>
<clients>2</clients>
<connections>907</connections>
<file_connections>379</file_connections>
<host>localhost</host>
<listener_connections>90</listener_connections>
<listeners>0</listeners>
<location>Earth</location>
<server_id>Icecast 2.5</server_id>
<source_client_connections>164</source_client_connections>
<source_relay_connections>0</source_relay_connections>
<source_total_connections>164</source_total_connections>
<sources>2</sources>
<stats>0</stats>
<stats_connections>0</stats_connections>
<source mount="/audio.ogg">
<title>All that she wants</title>
<artist>Ace of Base</artist>
<audio_bitrate>499821</audio_bitrate>
<audio_channels>2</audio_channels>
<audio_info>samplerate=44100;quality=10%2e0;channels=2</audio_info>
<audio_samplerate>44100</audio_samplerate>
<channels>2</channels>
<genre>various</genre>
<ice-bitrate>499</ice-bitrate>
<listener_peak>0</listener_peak>
<listeners>0</listeners>
<listenurl>http://localhost:8000/audio</listenurl>
<max_listeners>unlimited</max_listeners>
<public>1</public>
<quality>10.0</quality>
<samplerate>44100</samplerate>
<server_description>Teststream</server_description>
<server_name>Great audio stream</server_name>
<server_type>application/ogg</server_type>
<server_url>http://example.org/</server_url>
<slow_listeners>0</slow_listeners>
<source_ip>192.0.2.21</source_ip>
<subtype>Vorbis</subtype>
<total_bytes_read>3372153</total_bytes_read>
<total_bytes_sent>0</total_bytes_sent>
<user_agent>LadioCast/0.10.5 libshout/2.3.1</user_agent>
</source>
<source mount="/video.ogg">
<audio_bitrate>276000</audio_bitrate>
<audio_channels>6</audio_channels>
<audio_samplerate>48000</audio_samplerate>
<frame_rate>25.00</frame_rate>
<frame_size>720 x 576</frame_size>
<genre>various</genre>
<ice-bitrate>276</ice-bitrate>
<listener_peak>0</listener_peak>
<listeners>0</listeners>
<listenurl>http://localhost:8000/video</listenurl>
<max_listeners>unlimited</max_listeners>
<public>0</public>
<server_description>Unspecified description</server_description>
<server_name>Unspecified name</server_name>
<server_type>video/ogg</server_type>
<slow_listeners>0</slow_listeners>
<source_ip>192.0.2.21</source_ip>
<subtype>Vorbis/Theora</subtype>
<title>ERAGON</title>
<total_bytes_read>37136</total_bytes_read>
<total_bytes_sent>0</total_bytes_sent>
<user_agent>Lavf/55.20.0</user_agent>
<video_bitrate>200000</video_bitrate>
<video_quality>0</video_quality>
</source>
</icestats>
```
## General Statistics
<!-- FIXME -->
admin
: As set in the server config, this should contain contact details for getting in touch with the server administrator.
Usually this will be an email address, but as this can be an arbitrary string it could also be a phone number.
client_connections
: Client connections are basically anything that is not a source connection. These include listeners (not concurrent,
but cumulative), any admin function accesses, and any static content (file serving) accesses.
_This is an accumulating counter._
clients
: Number of currently active client connections.
connections
: The total of all inbound TCP connections since start-up.
_This is an accumulating counter._
file_connections
: _This is an accumulating counter._
host
: As set in the server config, this should be the full DNS resolveable name or FQDN for the host on which this
Icecast instance is running.
listener_connections
: Number of listener connections to mount points.
_This is an accumulating counter._
listeners
: Number of currently active listener connections.
location
: As set in the server config, this is a free form field that should describe e.g. the physical location of this server.
server_id
: Defaults to the version string of the currently running Icecast server. While not recommended it can be overriden in
the server config.
server_start_iso8601
: Timestamp of server startup in ISO 8601 date format.
server_start
: Timestamp of server startup in RFC 2822 date format. This field is deprecated and may be removed in a future version,
please use `server_start_iso8601` instead.
source_client_connections
: Source client connections are the number of times (cumulative since start-up, not just currently connected) a source
client has connected to Icecast.
_This is an accumulating counter._
source_relay_connections
: Number of outbound relay connections to (master) icecast servers.
_This is an accumulating counter._
source_total_connections
: Both clients and relays.
_This is an accumulating counter._
sources
: The total of currently connected sources.
stats
: The total of currently connected STATS clients.
stats_connections
: Number of times a stats client has connected to Icecast.
_This is an accumulating counter._
## Source-specific Statistics
Please note that the statistics are valid within the scope of the current source connection.
A reconnect or disconnection will reset those.
artist
: Artist of the current song
_Metadata set by source client_
title
: Title of the current song
_Metadata set by source client_
audio_bitrate
: Audio bitrate in bits/s
_Can be set by source client_
audio_channels
: Number of audio channels.
audio-info
: Information about the bitrate/samplerate/quality of the stream.
Also used for YP entries.
_Metadata set by source client_
Example:
`samplerate=44100;quality=10%2e0;channels=2` (LadioCast)
`ice-bitrate=128;ice-channels=2;ice-samplerate=44100` (Butt)
ice-bitrate
: Information about the audio bitrate (in kbit/s) of the stream.
_Can be set by source client_
samplerate
: Information about the samplerate of the stream.
_Can be set by source client_
quality
: Information about the audio quality of the stream.
_Metadata set by source client_
frame_rate
: Information about the framerate of the stream.
_Only present for video streams_
frame_size
: Information about the frame size of the stream.
_Only present for video streams_
video_bitrate
: Information about the video bitrate of the stream.
_Only present for video streams_
video_quality
: Information about the video quality of the stream.
_Only present for video streams_
server_name
: Stream name
_Metadata set by source client_
server_description
: Stream description
_Metadata set by source client_
server_type
: MIME-type for the stream currently active on this mountpoint.
subtype
: MIME-subtype, can be e.g. codecs like Opus, Vorbis, Theora.
Separated with `/`.
listener_peak
: Peak concurrent number of listener connections for this mountpoint.
listeners
: The number of currently connected listeners.
listenurl
: URL to this mountpoint. (This is not aware of aliases)
max_listeners
: Maximum number of listeners permitted to concurrently connect to this mountpoint.
public
: Flag that indicates whether this mount is to be listed on a YP.
_Set by source client, can be overriden by server config_
slow_listeners
: Number of slow listeners
source_ip
: IP address of the currently connected source client.
In case of relays the content of `<server>`.
stream_start_iso8601
: Timestamp of when the currently active source client connected to this mount point in ISO 8601 date format.
stream_start
: Timestamp of when the currently active source client connected to this mount point in RFC 2822 date format.
This field is deprecated and may be removed in a future version, please use `stream_start_iso8601` instead.
total_bytes_read
: Total number of bytes received from the source client.
total_bytes_sent
: Total number of bytes sent to all listener connections since last source connect.
user_agent
: HTTP user agent string as sent by the source client.
Additional data can be accessed through the admin interface, as every page of the admin
interface has an XML equivalent.
---
title: Win32 Specifics
version: 2.4.99.1
---
{::options auto_ids="true" /}
<div class="article" markdown="1">
The Win32 port of Icecast 2 is a simple command line application,
it used to be a UI framework around the core Icecast 2 server.
The GUI is no longer necessary as Icecast has achieved all of its
functionality in its web interface.
Most of the features of Icecast 2 are available in the Win32 port.
__A notable absence is IPv6 support.__
We are planning to reintroduce the capability to start Icecast
as a Windows Service in the 2.5.0 release.
</div>
---
title: YP Directories
version: 2.4.99.1
---
{::options auto_ids="true" /}
<div class="article" markdown="1">
# Overview
A YP directory is a listing of broadcast streams. Icecast has it own YP directory located at
[http://dir.xiph.org](http://dir.xiph.org). Currently Icecast can only be listed in an Icecast-supported YP directory.
This means that you cannot list your stream in the Shoutcast YP directory, due to their terms of service.
In the Icecast configuration file are all the currently available YP directory servers. Listing your stream in a YP is
a combination of settings in the Icecast configuration file and also in your source client. It is of great importance
to configure Icecast correctly, as even one wrong setting can prevent listings to be accepted by a YP directory.
</div>
<div class="article" markdown="1">
# Configuring Icecast for YP Support
First of all, Icecast must have been built with YP support. This is automatically done if you have libcurl installed.
If libcurl is not detected when icecats is compiled, then YP support is disabled.
If Icecast has been built with YP support, then the following configuration options control the YP directory settings:
{% highlight xml %}
<directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://dir.xiph.org/cgi-bin/yp-cgi</yp-url>
</directory>
{% endhighlight %}
Multiple directory XML chunks can be specified in order to be listed in multiple directories.
## Further options that play a significant role in YP listings
### `<hostname>`
The hostname option **MUST** be set to a name that resolves to the machine this Icecast server runs on.
### `<listener-socket><port>`
The **first** `listener-socke`+`port` entry is used to build the URL advertized to the YP server.
### `<listener-socket><bind-address>`
If you don't specify an explicit `bind-address`, including `::` and `0.0.0.0`, then the default
bind behaviour of your operating system will apply, this may have unexpected consequences for dual-stack
(IPv6 and IPv4) setups.
If your hostname resolves to both an AAAA and an A record (IPv6 and IPv4), then you **MUST** verify,
that Icecast listens to both. If in doubt create two listener-socket entries and use `::` and `0.0.0.0`
as the respective `bind-address`.
### `<admin>` contact
If you are listing on a YP, then this field **MUST** contain a valid email address of a technical contact
on your side. YP admins will use this to reach you in case your server is misconfigured and causes problems
for the YP directory. An invalid or unreachable address is likely to get your radio/server/network banned from YP.
### Verifying the advertized URL
After adjusting the settings and configuring your source client, you should verify setup:
Go to the Icecast web interface, specifically the admin part `/admin/` and look for the `listenurl` values
of your streams. These URLs **MUST** work from the public internet, or your listings will fail.
This is also one of the checks performed by a YP server. Common misconfigurations are:
* `<hostname>` set to `localhost`
* `<hostname>` set to some address that does **NOT** point to the Icecast server
* hostname has AAAA record but Icecast not bound to `::`
* multiple `<listener-socket>` entries, but the first one is not publicly reachable
</div>
<div class="article" markdown="1">
# Configuring Your Source Client for YP Support
This is usually covered in the source client documentation. More specifically, the source client needs to provide
the HTTP header `Ice-Public: 1` on connect in order to enable YP listing of the stream.
This can however be overridden in the server side mount point settings, refer to “[Icecast Config File](config-file.html#mountsettings)