From a517f4c1ce25c236a55edf200990f06b3099559b Mon Sep 17 00:00:00 2001 From: "Thomas B. \"dm8tbr\" Ruecker" Date: Sun, 4 May 2014 15:37:50 +0000 Subject: [PATCH] Refactored docs about client authentication. svn path=/icecast/trunk/icecast/; revision=19125 --- doc/Makefile.am | 2 +- ...2_listenerauth.html => icecast2_auth.html} | 54 +++++++++++++++---- doc/icecast2_config_file.html | 4 +- doc/index.html | 2 +- 4 files changed, 48 insertions(+), 14 deletions(-) rename doc/{icecast2_listenerauth.html => icecast2_auth.html} (80%) diff --git a/doc/Makefile.am b/doc/Makefile.am index 7d2d8c45..af7aa67d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 diff --git a/doc/icecast2_listenerauth.html b/doc/icecast2_auth.html similarity index 80% rename from doc/icecast2_listenerauth.html rename to doc/icecast2_auth.html index 2266594a..7341df36 100644 --- a/doc/icecast2_listenerauth.html +++ b/doc/icecast2_auth.html @@ -7,7 +7,7 @@
-

Icecast 2 Listener Authentication

+

Icecast 2 Authentication



@@ -85,17 +85,17 @@ config file. The following shows the list of options available :

<mount> <mount-name>/example.ogg</mount-name> <authentication type="url"> - <option name="mount_add" value="http://myauthserver.com/stream_start.php"/> - <option name="mount_remove" value="http://myauthserver.com/stream_end.php"/> - <option name="listener_add" value="http://myauthserver.com/listener_joined.php"/> - <option name="listener_remove" value="http://myauthserver.com/listener_left.php"/> + <option name="mount_add" value="http://auth.example.org/stream_start.php"/> + <option name="mount_remove" value="http://auth.example.org/stream_end.php"/> + <option name="listener_add" value="http://auth.example.org/listener_joined.php"/> + <option name="listener_remove" value="http://auth.example.org/listener_left.php"/> <option name="username" value="user"/> <option name="password" value="pass"/> <option name="auth_header" value="icecast-auth-user: 1"/> <option name="timelimit_header" value="icecast-auth-timelimit:"/> <option name="headers" value="x-pragma,x-token"/> <option name="header_prefix" value="ClientHeader."/> - <option name="stream_auth" value="http://myauthserver.com/source.php"/> + <option name="stream_auth" value="http://auth.example.org/source.php"/> </authentication> </mount> @@ -107,7 +107,7 @@ is passed for this, but can be used to initialise any details the auth server ma

POST details are

-    action=mount_add&mount=/live&server=myserver.com&port=8000
+    action=mount_add&mount=/live&server=icecast.example.org&port=8000

Here the details indicate the server name (<hostname>) and mountpoint starting up

mount_remove

@@ -115,7 +115,7 @@ is passed for this, but can be used to initialise any details the auth server ma listener details are passed.

POST details are

-    action=mount_remove&mount=/live&server=myserver.com&port=8000
+    action=mount_remove&mount=/live&server=icecast.example.org&port=8000

like the start option, server name and mountpoint are provided

@@ -126,7 +126,7 @@ unless the auth server sends back a response header which may be stated in the '

POST details are

-    action=listener_add&server=myserver.com&port=8000&client=1&mount=/live&user=&pass=&ip=127.0.0.1&agent=My%20player
+    action=listener_add&server=icecast.example.org&port=8000&client=1&mount=/live&user=&pass=&ip=127.0.0.1&agent=My%20player

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

This URL is for when a listener connection closes.

POST details are

-    action=listener_remove&server=myserver.com&port=8000&client=1&mount=/live&user=&pass=&duration=3600&ip=127.0.0.1&agent=My%20player
+    action=listener_remove&server=icecast.example.org&port=8000&client=1&mount=/live&user=&pass=&duration=3600&ip=127.0.0.1&agent=My%20player

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

@@ -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

+
+

Source Authentication

+

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.

+ +

To define source authentication, a group of tags are specified in the <mount> +group relating to the mountpoint.

+
+

The following authentication mechanisms can apply to sources

+ +
+ +
+ +

URL authentication: stream_auth

+

A <mount> can contain a section <authentication type="url"> +and therein <option name="stream_auth" value="http://auth.example.org/source.php"/>. +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) +

+

POST details are

+
+    action=stream_auth&mount=/stream.ogg&ip=192.0.2.0&server=icecast.example.org&port=8000&user=source&pass=password&admin=1
+
+

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 &admin=1 is added to the POST details.

diff --git a/doc/icecast2_config_file.html b/doc/icecast2_config_file.html index 0649110c..a3dee6c8 100644 --- a/doc/icecast2_config_file.html +++ b/doc/icecast2_config_file.html @@ -480,7 +480,7 @@ Do not set this value unless you are sure that the source clients connecting to

password

An optional value which will set the password that a source must use to connect using this mountpoint.
-There is also a URL based authentication method for sources that can be used instead. +There is also a URL based authentication method for sources that can be used instead.

max-listeners

@@ -634,7 +634,7 @@ relay to be shown

authentication

-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 here. +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 here.

on-connect

diff --git a/doc/index.html b/doc/index.html index b2f41bf5..ca7f0e47 100644 --- a/doc/index.html +++ b/doc/index.html @@ -18,7 +18,7 @@
  • Server Statistics
  • Relaying
  • Listing in a YP directory
    • -
  • Listener Authentication
    • +
  • Authentication
  • Win32 specific documentation
  • Glossary
  • FAQ