yp.html 7.77 KB
Newer Older
ePirat's avatar
ePirat committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
<!DOCTYPE html>
<html lang="en">
	<title>Icecast Docs Docs &mdash; YP Directories</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" />


    <div class="header">
      <h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>

    <div class="section">
19 20
      <h2>Icecast Docs &mdash; YP Directories</h2>
ePirat's avatar
ePirat committed
21 22 23
<div class="article">
  <h3 id="overview">Overview</h3>
  <p>A YP directory is a listing of broadcast streams. Icecast has it own YP directory located at
ePirat's avatar
ePirat committed
<a href="http://dir.xiph.org">http://dir.xiph.org</a>. Currently Icecast can only be listed in an Icecast-supported YP directory.<br />
This means that you cannot list your stream in the Shoutcast YP directory, due to their terms of service.</p>
ePirat's avatar
ePirat committed
27 28

  <p>In the Icecast configuration file are all the currently available YP directory servers. Listing your stream in a YP is
29 30
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.</p>
ePirat's avatar
ePirat committed
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46


<div class="article">
  <h3 id="configuring-icecast-for-yp-support">Configuring Icecast for YP Support</h3>
  <p>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.<br />
If Icecast has been built with YP support, then the following configuration options control the YP directory settings:</p>

  <div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;directory&gt;</span>
    <span class="nt">&lt;yp-url-timeout&gt;</span>15<span class="nt">&lt;/yp-url-timeout&gt;</span>
    <span class="nt">&lt;yp-url&gt;</span>http://dir.xiph.org/cgi-bin/yp-cgi<span class="nt">&lt;/yp-url&gt;</span>
<span class="nt">&lt;/directory&gt;</span></code></pre></div>

  <p>Multiple directory XML chunks can be specified in order to be listed in multiple directories.</p>

47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
  <h4 id="further-options-that-play-a-significant-role-in-yp-listings">Further options that play a significant role in YP listings</h4>

  <h5 id="hostname"><code>&lt;hostname&gt;</code></h5>
  <p>The hostname option <strong>MUST</strong> be set to a name that resolves to the machine this Icecast server runs on.</p>

  <h5 id="listener-socketport"><code>&lt;listener-socket&gt;&lt;port&gt;</code></h5>
  <p>The <strong>first</strong> <code>listener-socke</code>+<code>port</code> entry is used to build the URL advertized to the YP server.</p>

  <h5 id="listener-socketbind-address"><code>&lt;listener-socket&gt;&lt;bind-address&gt;</code></h5>
  <p>If you don’t specify an explicit <code>bind-address</code>, including <code>::</code> and <code></code>, then the default
bind behaviour of your operating system will apply, this may have unexpected consequences for dual-stack
(IPv6 and IPv4) setups.</p>

  <p>If your hostname resolves to both an AAAA and an A record (IPv6 and IPv4), then you <strong>MUST</strong> verify,
that Icecast listens to both. If in doubt create two listener-socket entries and use <code>::</code> and <code></code>
as the respective <code>bind-address</code>.</p>

  <h5 id="admin-contact"><code>&lt;admin&gt;</code> contact</h5>
  <p>If you are listing on a YP, then this field <strong>MUST</strong> 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.</p>

  <h5 id="verifying-the-advertized-url">Verifying the advertized URL</h5>

  <p>After adjusting the settings and configuring your source client, you should verify setup: <br />
Go to the Icecast web interface, specifically the admin part <code>/admin/</code> and look for the <code>listenurl</code> values 
of your streams. These URLs <strong>MUST</strong> work from the public internet, or your listings will fail.</p>

  <p>This is also one of the checks performed by a YP server. Common misconfigurations are:<br />
 * <code>&lt;hostname&gt;</code> set to <code>localhost</code>
 * <code>&lt;hostname&gt;</code> set to some address that does <strong>NOT</strong> point to the Icecast server
 * hostname has AAAA record but Icecast not bound to <code>::</code>
 * multiple <code>&lt;listener-socket&gt;</code> entries, but the first one is not publicly reachable</p>

ePirat's avatar
ePirat committed
81 82 83 84 85 86

<div class="article">
  <h3 id="configuring-your-source-client-for-yp-support">Configuring Your Source Client for YP Support</h3>
  <p>This is usually covered in the source client documentation. More specifically, the source client needs to provide
the HTTP header <code>Ice-Public: 1</code> on connect in order to enable YP listing of the stream.<br />
This can however be overridden in the server side mount point settings, refer to “<a href="config-file.html#mountsettings">Icecast Config File</a>
ePirat's avatar
ePirat committed
88 89 90 91 92 93
for further details.<br />
If a mountpoint is being listed on a YP, then you will see some additional statistics relating to the YP such as
<code>last-touch</code>, <code>currently-playing</code>, etc.</p>


94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120
<div class="article">
  <h3 id="troubleshooting">Troubleshooting</h3>
  <p>As with all Icecast problems, the error log is the goto place to start. If necessary temporary increase the log level to 
<code>4</code> (debug) and reload the Icecast config. All relevant messages will contain <code>YP</code>. Especially those messages that tell
you that something <code>failed</code> will contain important hints and or messages from the YP 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
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
for further hints.</p>

  <p>Should you still have problems listing on <a href="dir.xiph.org">http://dir.xiph.org</a>, then please:
* set your logging to <code>4</code> (debug)
* reload/restart Icecast
* make sure your streams are running and marked public (either by source setting or mountpoint override)
* wait for <strong>one hour</strong>
* filter the error log for messages from the last hour, that are beginning with <code>yp/</code>
* join the <a href="Icecast users mailing list">http://lists.xiph.org/mailman/listinfo/icecast</a> (else the following step will fail!)
* send a mail to <a href="icecast@xiph.org">mailto:icecast@xiph.org</a> containing:
 1. The public URL of your Icecast server - e.g. <code>http://icecast.example.org:8000/</code> (Even if you have removed the status pages! This does <strong>NOT</strong> mean your homepage.)
 2. The <code>&lt;hostname&gt;</code>, <code>&lt;listen-socket&gt;</code> and <code>&lt;directory&gt;</code> sections of your <code>icecast.xml</code>
 3. The <em>filtered</em> error.log prepared previously (as an attachment)
* wait for replies from the mailing list</p>


ePirat's avatar
ePirat committed
121 122 123

    <div class="footer">
124 125 126 127 128
	<p><a href="https://plus.google.com/100957455777699991449/about">
		<img alt="Google+" title="Find uns on Google+" src="/assets/img/google-plus.svg" style="width: 20px;">
	<p>&copy; 2004-2014 Xiph.Org. All rights reserved.</p>
ePirat's avatar
ePirat committed
129 130 131 132 133
      <p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>