Icecast documentation update for stream_auth.

svn path=/icecast/trunk/icecast/; revision=18808

doc/icecast2_config_file.html

@@ -434,9 +434,8 @@ The source of the relay may require authentication itself, if so state the passw
         <hidden>1</hidden>
         <burst-size>65536</burst-size>
         <mp3-metadata-interval>4096</mp3-metadata-interval>
-        <authentication type="htpasswd">
-                <option name="filename" value="myauth"/>
-                <option name="allow_duplicate_users" value="0"/>
+        <authentication type="xxxxxx">
+                <!-- See listener authentiaction documentation -->
         </authentication>
         <on-connect>/home/icecast/bin/source-start</on-connect>
         <on-disconnect>/home/icecast/bin/source-end</on-disconnect>
@@ -464,7 +463,8 @@ Do not set this value unless you are sure that the source clients connecting to
 </div>
 <h4>password</h4>
 <div class="indentedbox">
-An optional value which will set the password that a source must use to connect using this mountpoint.
+An optional value which will set the password that a source must use to connect using this mountpoint.<br />
+There is also a <a href="icecast2_listenerauth.html#stream_auth">URL based authentication method</a> for sources that can be used instead.
 </div>
 <h4>max-listeners</h4>
 <div class="indentedbox">
@@ -618,7 +618,7 @@ relay to be shown
 </div>
 <h4>authentication</h4>
 <div class="indentedbox">
-This specifies that the named mount point will require listener authentication.  Currently, we only support a file-based authentication scheme (type=htpasswd).  Users and encrypted password are placed in this file (separated by a :) and all requests for this mountpoint will require that a user and password be supplied for authentication purposes.  These values are passed in via normal HTTP Basic Authentication means (i.e. http://user:password@stream:port/mountpoint.ogg).  Users and Passwords are maintained via the web admin interface.  A mountpoint configured with an authenticator will display a red key next to the mount point name on the admin screens.  You can read more about listener authentication <a href="icecast2_listenerauth.html">here</a>.
+This specifies that the named mount point will require listener (or source) authentication.  Currently, we support a file-based authentication scheme (type=htpasswd) and URL based authentication request forwarding. A mountpoint configured with an authenticator will display a red key next to the mount point name on the admin screens.  You can read more about listener authentication and URL based source authentication <a href="icecast2_listenerauth.html">here</a>.
 </div>
 <h4>on-connect</h4>
 <div class="indentedbox">

doc/icecast2_listenerauth.html

@@ -95,6 +95,7 @@ config file.  The following shows the list of options available :</p>
             &lt;option name="timelimit_header" value="icecast-auth-timelimit:"/&gt;
             &lt;option name="headers"          value="x-pragma,x-token"/&gt;
             &lt;option name="header_prefix"    value="ClientHeader."/&gt;
+            &lt;option name="stream_auth" value="http://myauthserver.com/listener_left.php"/&gt;
         &lt;/authentication&gt;
     &lt;/mount&gt;
 </pre>
@@ -142,6 +143,22 @@ note that each option data is escaped before being passed via POST
 </pre>
 <p>Again this is similar to the add option, the difference being that a duration is passed
 reflecting the number of seconds the listener was connected for </p>
+<div id="stream_auth" >
+<h3>stream_auth</h3>
+<p>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
+</p>
+<p>POST details are</p>
+<pre>
+    action=stream_auth&amp;mount=/stream.ogg&amp;ip=192.0.2.0&amp;server=icecast.example.org&amp;port=8000&amp;user=source&amp;pass=password&amp;admin=1
+</pre>
+<p>The request contains: the mountpoint, the IP from which the source client is connecting,
+the hostname of the icecast server the client tries to connect to,
+the port of said server and finally username and password as sent by the source client. 
+As admin requests can come in for a stream (eg metadata update) these requests can be 
+issued while stream is active. For these &amp;admin=1 is added to the POST details.</p></div>
 <h3>auth_header</h3>
 <p>The expected response header to be returned that allows the authencation to take
 place may be specified here. The default is 
@@ -154,7 +171,7 @@ figure (which represents seconds) then that is how long the client will remain c
 </p>
 <h3>headers</h3>
 <p>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 send as post parameters.
+Those headers are prepended by the value of header_prefix and sent as post parameters.
 </p>
 <h3>header_prefix</h3>
 <p>This is the prefix used for passing client headers. See headers for details.