Skip to content

GitLab

Commit a517f4c1 authored by Thomas B. Rücker's avatar Thomas B. Rücker 😊
Browse files
Options

Refactored docs about client authentication. 

svn path=/icecast/trunk/icecast/; revision=19125
parent e812c463
Show whitespace changes
Inline Side-by-side
Showing with 48 additions and 14 deletions
doc/Makefile.am
View file @ a517f4c1
......@@ -6,7 +6,7 @@ docdir = $(datadir)/doc/icecast
doc_DATA = index.html icecast2_admin.html icecast2_basicsetup.html \
icecast2_config_file.html icecast2_faq.html icecast2_glossary.html \
icecast2_introduction.html icecast2_relay.html icecast2_stats.html \
icecast2_win32.html icecast2_yp.html icecast2_listenerauth.html icecast2_changes.html \
icecast2_win32.html icecast2_yp.html icecast2_auth.html icecast2_changes.html \
listener_auth1.jpg listener_auth2.jpg listener_auth3.jpg \
masterslave.png relay.png
......
doc/icecast2_listenerauth.html → doc/icecast2_auth.html
View file @ a517f4c1
......@@ -7,7 +7,7 @@
</head>
<body>
<div class="boxtest">
<h1>Icecast 2 Listener Authentication</h1>
<h1>Icecast 2 Authentication</h1>
<hr id='titlebar' />
<br />
<br />
......@@ -85,17 +85,17 @@ config file. The following shows the list of options available :</p>
&lt;mount&gt;
&lt;mount-name&gt;/example.ogg&lt;/mount-name&gt;
&lt;authentication type="url"&gt;
&lt;option name="mount_add" value="http://myauthserver.com/stream_start.php"/&gt;
&lt;option name="mount_remove" value="http://myauthserver.com/stream_end.php"/&gt;
&lt;option name="listener_add" value="http://myauthserver.com/listener_joined.php"/&gt;
&lt;option name="listener_remove" value="http://myauthserver.com/listener_left.php"/&gt;
&lt;option name="mount_add" value="http://auth.example.org/stream_start.php"/&gt;
&lt;option name="mount_remove" value="http://auth.example.org/stream_end.php"/&gt;
&lt;option name="listener_add" value="http://auth.example.org/listener_joined.php"/&gt;
&lt;option name="listener_remove" value="http://auth.example.org/listener_left.php"/&gt;
&lt;option name="username" value="user"/&gt;
&lt;option name="password" value="pass"/&gt;
&lt;option name="auth_header" value="icecast-auth-user: 1"/&gt;
&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/source.php"/&gt;
&lt;option name="stream_auth" value="http://auth.example.org/source.php"/&gt;
&lt;/authentication&gt;
&lt;/mount&gt;
</pre>
......@@ -107,7 +107,7 @@ is passed for this, but can be used to initialise any details the auth server ma
</p>
<p>POST details are</p>
<pre>
action=mount_add&amp;mount=/live&amp;server=myserver.com&amp;port=8000
action=mount_add&amp;mount=/live&amp;server=icecast.example.org&amp;port=8000
</pre>
<p>Here the details indicate the server name (&lt;hostname&gt;) and mountpoint starting up</p>
<h3>mount_remove</h3>
......@@ -115,7 +115,7 @@ is passed for this, but can be used to initialise any details the auth server ma
listener details are passed.</p>
<p>POST details are</p>
<pre>
action=mount_remove&amp;mount=/live&amp;server=myserver.com&amp;port=8000
action=mount_remove&amp;mount=/live&amp;server=icecast.example.org&amp;port=8000
</pre>
<p>like the start option, server name and mountpoint are provided</p>
</p>
......@@ -126,7 +126,7 @@ unless the auth server sends back a response header which may be stated in the '
</p>
<p>POST details are</p>
<pre>
action=listener_add&amp;server=myserver.com&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;ip=127.0.0.1&amp;agent=My%20player
action=listener_add&amp;server=icecast.example.org&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;ip=127.0.0.1&amp;agent=My%20player
</pre>
<p>There are more details with this, client is the unique ID for the client within icecast,
user and pass may be blank but come from the HTTP basic auth that the listener states, ip
......@@ -139,7 +139,7 @@ note that each option data is escaped before being passed via POST
<p>This URL is for when a listener connection closes.</p>
<p>POST details are</p>
<pre>
action=listener_remove&amp;server=myserver.com&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;duration=3600&amp;ip=127.0.0.1&amp;agent=My%20player
action=listener_remove&amp;server=icecast.example.org&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;duration=3600&amp;ip=127.0.0.1&amp;agent=My%20player
</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>
......@@ -183,6 +183,40 @@ standard HTTP basic authentication, and in general, many media players support t
support anything at all. Winamp and Foobar2000 support HTTP basic authentication on windows,
and XMMS supports it on unix platforms. Winamp/XMMS as least support the passing of query
parameters, other players may also do</p>
<br />
<h2>Source Authentication</h2>
<p>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.</p>
<p>To define source authentication, a group of tags are specified in the &lt;mount&gt;
group relating to the mountpoint.</p>
<br />
<p>The following authentication mechanisms can apply to sources</p>
<ul>
<li>BASIC - &lt;password&gt; and possibly &lt;username&gt; in the &lt;mount&gt; section</li>
<li>URL - issue web requests (eg PHP) to match authentication</li>
</ul>
<br />
<div id="stream_auth" >
<h3>URL authentication: stream_auth</h3>
<p>A &lt;mount&gt; can contain a section &lt;authentication type="url"&gt;
and therein &lt;option name="stream_auth" value="http://auth.example.org/source.php"/&gt;.
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)
</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>
</div>
</body>
</html>
doc/icecast2_config_file.html
View file @ a517f4c1
......@@ -480,7 +480,7 @@ Do not set this value unless you are sure that the source clients connecting to
<h4>password</h4>
<div class="indentedbox">
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.
There is also a <a href="icecast2_auth.html#stream_auth">URL based authentication method</a> for sources that can be used instead.
</div>
<h4>max-listeners</h4>
<div class="indentedbox">
......@@ -634,7 +634,7 @@ relay to be shown
</div>
<h4>authentication</h4>
<div class="indentedbox">
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>.
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_auth.html">here</a>.
</div>
<h4>on-connect</h4>
<div class="indentedbox">
......
doc/index.html
View file @ a517f4c1
......@@ -18,7 +18,7 @@
<li><a href="icecast2_stats.html">Server Statistics</a></li>
<li><a href="icecast2_relay.html">Relaying</a></li>
<li><a href="icecast2_yp.html">Listing in a YP directory</a></li>
<li><a href="icecast2_listenerauth.html">Listener Authentication</a></li>
<li><a href="icecast2_auth.html">Authentication</a></li>
<li><a href="icecast2_win32.html">Win32 specific documentation</a></li>
<li><a href="icecast2_glossary.html">Glossary</a></li>
<li><a href="icecast2_faq.html">FAQ</a></li>
......
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