Commit 3cc0cca0 authored by Thomas B. Rücker's avatar Thomas B. Rücker 😊

YP documentation cleanup & whitespace

Removed mentions of YP, as that's an internal term.
Removed trailin spaces from a lot of lines in the process.
parent 84c1be65
......@@ -109,7 +109,7 @@ burst-size
This section contains all the usernames and passwords used for administration purposes or to connect sources and relays.
For more information, refer to the [Authentication](auth.md) Page.
# YellowPage Directory Settings
# Public Directory Publishing Settings
```xml
<directory>
......@@ -118,9 +118,9 @@ For more information, refer to the [Authentication](auth.md) Page.
</directory>
```
This section contains all the settings for listing a stream on any of the Icecast YP Directory servers.
This section contains all the settings for listing a stream on any of the Icecast Directory servers.
Multiple occurances of this section can be specified in order to be listed on multiple directory servers.
For more Information see the [Listing in a YellowPage Directory](yp.md) Page.
For more Information see the [Listing in a Directory](yp.md) Page.
yp-url-timeout
: This value is the maximum time Icecast will wait for a response from a particular directory server.
......@@ -357,38 +357,38 @@ charset
public
: The default setting for this is `-1` indicating that it is up to the source client or relay to determine if this mountpoint
should advertise. A setting of `0` will prevent any advertising and a setting of `1` will force it to advertise.
If you do force advertising you may need to set other settings listed below as the YP server can refuse to advertise
If you do force advertising you may need to set other settings listed below as the directory server can refuse to advertise
if there is not enough information provided.
stream-name
: Setting this will add the specified name to the stats (and therefore YP) for this mountpoint even if the source client/relay provide one.
: Setting this will add the specified name to the stats (and therefore directory listings) for this mountpoint even if the source client/relay provide one.
stream-description
: Setting this will add the specified description to the stats (and therefore YP) for this mountpoint even if the source client/relay provide one.
: Setting this will add the specified description to the stats (and therefore directory listings) for this mountpoint even if the source client/relay provide one.
stream-url
: Setting this will add the specified URL to the stats (and therefore YP) for this mountpoint even if the source client/relay provide one.
: Setting this will add the specified URL to the stats (and therefore directory listings) for this mountpoint even if the source client/relay provide one.
The URL is generally for directing people to a website.
genre
: Setting this will add the specified genre to the stats (and therefore YP) for this mountpoint even if the source client/relay provide one.
This can be anything be using certain key words can help searches in the YP directories.
: Setting this will add the specified genre to the stats (and therefore directory listings) for this mountpoint even if the source client/relay provide one.
This can be anything be using certain key words can help searches in the directories.
bitrate
: Setting this will add the specified bitrate to the stats (and therefore YP) for this mountpoint even if the source client/relay provide one.
: Setting this will add the specified bitrate to the stats (and therefore directory listings) for this mountpoint even if the source client/relay provide one.
This is stated in kbps.
type
: Setting this will add the specified mime type to the stats (and therefore YP) for this mountpoint even if the source client/relay provide one.
: Setting this will add the specified mime type to the stats (and therefore directory listings) for this mountpoint even if the source client/relay provide one.
It is very unlikely that this will be needed.
subtype
: Setting this will add the specified subtype to the stats (and therefore YP) for this mountpoint.
The subtype is really to help the YP server to identify the components of the type.
An example setting is vorbis/theora do indicate the codecs in an Ogg stream
: Setting this will add the specified subtype to the stats (and therefore directory listings) for this mountpoint.
The subtype is really to help the directory server to identify the components of the type.
An example setting is vorbis/theora and indicates the codecs in an Ogg stream
burst-size
: This optional setting allows for providing a burst size which overrides the default burst size as defined in limits.
: This optional setting allows for providing a burst size which overrides the default burst size as defined in limits.
The value is in bytes.
mp3-metadata-interval
......
......@@ -111,14 +111,14 @@ admin
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.
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.
: The total of all inbound TCP connections since start-up.
_This is an accumulating counter._
file_connections
......@@ -129,7 +129,7 @@ host
Icecast instance is running.
listener_connections
: Number of listener connections to mount points.
: Number of listener connections to mount points.
_This is an accumulating counter._
listeners
......@@ -151,15 +151,15 @@ server_start
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.
client has connected to Icecast.
_This is an accumulating counter._
source_relay_connections
: Number of outbound relay connections to (master) icecast servers.
: Number of outbound relay connections to (master) icecast servers.
_This is an accumulating counter._
source_total_connections
: Both clients and relays.
: Both clients and relays.
_This is an accumulating counter._
sources
......@@ -169,23 +169,23 @@ 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._
: 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.
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
: Artist of the current song
_Metadata set by source client_
title
: Title of the current song
: Title of the current song
_Metadata set by source client_
audio_bitrate
: Audio bitrate in bits/s
: Audio bitrate in bits/s
_Can be set by source client_
audio_channels
......@@ -193,53 +193,53 @@ 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)
Also used for directory listings.
_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.
: 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.
: Information about the samplerate of the stream.
_Can be set by source client_
quality
: Information about the audio quality of the stream.
: Information about the audio quality of the stream.
_Metadata set by source client_
frame_rate
: Information about the framerate of the stream.
: Information about the framerate of the stream.
_Only present for video streams_
frame_size
: Information about the frame size of the stream.
: Information about the frame size of the stream.
_Only present for video streams_
video_bitrate
: Information about the video bitrate of the stream.
: Information about the video bitrate of the stream.
_Only present for video streams_
video_quality
: Information about the video quality of the stream.
: Information about the video quality of the stream.
_Only present for video streams_
server_name
: Stream name
: Stream name
_Metadata set by source client_
server_description
: Stream 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.
: MIME-subtype, can be e.g. codecs like Opus, Vorbis, Theora.
Separated with `/`.
listener_peak
......@@ -255,14 +255,14 @@ 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.
: Flag that indicates whether this mount is to be listed on a directory.
_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.
: IP address of the currently connected source client.
In case of relays the content of `<server>`.
stream_start_iso8601
......
# 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.
A YP directory is a listing of broadcast streams. The Icecast project has it own directory located at
[http://dir.xiph.org](http://dir.xiph.org).
In the Icecast configuration file are all the currently available YP directory servers. Listing your stream in a YP is
The Icecast configuration file contains entries for all the currently enabled directory servers. Listing your stream in a directory 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.
to configure Icecast correctly, as even one wrong setting can prevent listings to be accepted by a directory.
# 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:
# Configuring Icecast for Directory Support
First of all, Icecast must have been built with directory support. This is automatically done if you have libcurl installed.
If libcurl is not detected when icecast is compiled, then directory support is disabled and listing attempts will fail.
If Icecast has been built with directory support, then the following configuration options control the directory settings:
```xml
<directory>
......@@ -22,69 +21,75 @@ If Icecast has been built with YP support, then the following configuration opti
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
In the default configuration the directory settings are commented out by being enclosed in `<!--` and `-->`.
By removing these comment markers and restarting/reloading Icecast the entry becomes active.
## Further options that play a significant role in directory listings
hostname
: The hostname option **MUST** be set to a name that resolves to the machine this Icecast server runs on.
: The hostname option **MUST** be set to a name that resolves to the machine this Icecast server runs on
(IP address is also permissible, but proper domain name is preferred).
listener-socket port
: The **first** `listener-socket`+`port` entry is used to build the URL advertized to the YP server.
: The **first** `listener-socket`+`port` entry in the configuration is used to build the URL advertized to the directory 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.
(IPv6 and IPv4) setups. Icecast may end up only listening on IPv4.
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
: 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.
: If you are listing on a directory, then this field **MUST** contain a valid email address of a technical contact
on your side. Directory admins will use this to reach you in case your server is misconfigured and causes problems
for listeners and the directory. An invalid or unreachable address is likely to get your radio/server/network banned from the directory.
### Verifying the advertized URL
After adjusting the settings and configuring your source client, you should verify setup:
After adjusting the settings and configuring your source client, you should verify your 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:
This is also one of the checks performed by a directory 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 `::`
* `<hostname>` set to `localhost` instead of correct domain name
* `<hostname>` set to some address that does **NOT** point to the Icecast server, but e.g. a homepage
* hostname has AAAA record but Icecast not bound to IPv6
* multiple `<listener-socket>` entries, but the first one is not publicly reachable
# Configuring Your Source Client for YP Support
# Configuring Your Source Client for Directory Listings
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.
the HTTP header `Ice-Public: 1` on connect in order to enable directory 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)
for further details.
If a mountpoint is being listed on a YP, then you will see some additional statistics relating to the YP such as
If a mountpoint is being listed on a directory, then you will see some additional statistics relating to the directory such as
`last-touch`, `currently-playing`, etc.
# Troubleshooting
As with all Icecast problems, the error log is the goto place to start. If necessary temporary increase the log level to
`4` (debug) and reload the Icecast config. All relevant messages will contain `YP`. Especially those messages that tell
you that something `failed` will contain important hints and or messages from the YP server. If your entry submission
you that something `failed` will contain important hints and or messages from the directory server. If your entry submission
is directly rejected the server will tell why, if your entry gets delisted after submission, then you will see
updates/touches fail. Depending on the YP server the stream reachability check will be deferred, so you will see
updates/touches fail. Depending on the directory server the stream reachability check will be deferred, so you will see
a successfull initial submission, but if your stream is found to be unreachable it will be delisted and updates will fail.
Please note that YP directories will check both IPv6 and IPv4 availability of streams. See the list of common misconfigurations
Please note that directories will check both IPv6 and IPv4 availability of streams. See the list of common misconfigurations
for further hints.
Should you still have problems listing on [http://dir.xiph.org](dir.xiph.org), then please:
* Set your logging to `4` (debug)
* Reload/restart Icecast
* Go through the common misconfigurations
* Make sure your streams are running and marked public (either by source setting or mountpoint override)
* Wait for **one hour**
* Filter the error log for messages from the last hour, that are beginning with `yp/`
* Filter the error log for messages, from the last hour, that are beginning with `yp/`
* Join the [http://lists.xiph.org/mailman/listinfo/icecast](Icecast users mailing list) (else the following step will fail!)
* Send a mail to [mailto:icecast@xiph.org](icecast@xiph.org) containing:
1. The public URL of your Icecast server - e.g. `http://icecast.example.org:8000/` (Even if you have removed the status pages! This does **NOT** mean your homepage.)
2. The `<hostname>`, `<listen-socket>` and `<directory>` sections of your `icecast.xml`
4. Your Icecast version and operating system / distribution
3. The *filtered* error.log prepared previously (as an attachment)
* Wait for replies from the mailing list
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment