diff --git a/configure.ac b/configure.ac index 450e232e6d5af1d5ee97394ea4507391338960d3..0b815fcfe5dffd5cd4da1acce7d41bcd905eda1e 100644 --- a/configure.ac +++ b/configure.ac @@ -141,6 +141,21 @@ XIPH_PATH_OPENSSL([ [ AC_MSG_NOTICE([SSL disabled!]) ]) + +dnl Documentation + +AC_PATH_PROG([MKDOCS], [mkdocs], [no]) + +AS_IF([test "$MKDOCS" = "no"], [ + AC_MSG_WARN([mkdocs not found - generating docs will be disabled]) +]) +AM_CONDITIONAL([HAVE_MKDOCS], [test ! "$MKDOCS" = "no"]) + +AM_COND_IF([HAVE_MKDOCS], [ + AC_CONFIG_FILES([doc/mkdocs.yml]) +]) + + dnl Make substitutions AC_SUBST(XIPH_CPPFLAGS) @@ -161,8 +176,6 @@ AC_SUBST(KATE_LIBS) AC_OUTPUT([Makefile conf/Makefile src/Makefile src/common/avl/Makefile src/common/httpp/Makefile src/common/thread/Makefile src/common/log/Makefile -src/common/net/Makefile src/common/timing/Makefile doc/Makefile doc/img/Makefile -doc/assets/Makefile doc/assets/css/Makefile doc/assets/font/Makefile -doc/assets/img/Makefile web/Makefile web/assets/Makefile web/assets/css/Makefile +src/common/net/Makefile src/common/timing/Makefile doc/Makefile web/Makefile web/assets/Makefile web/assets/css/Makefile web/assets/font/Makefile admin/Makefile admin/includes/Makefile win32/Makefile examples/Makefile]) diff --git a/doc/Makefile.am b/doc/Makefile.am index 3b559ed09d65c6c25c7ec534361f5a4f03c0e73e..49d735ea96b8f58bee7b80ac39e071121363f2b9 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,12 +1,46 @@ ## Process this file with automake to produce Makefile.in -AUTOMAKE_OPTIONS = foreign - -SUBDIRS = assets img +EXTRA_DIST = \ + mkdocs.yml \ + docs/img/icecast_shema.svg \ + docs/admin_interface.md \ + docs/auth.md \ + docs/basic_setup.md \ + docs/config_file.md \ + docs/index.md \ + docs/introduction.md \ + docs/relaying.md \ + docs/server_stats.md \ + docs/win32.md \ + docs/yp.md docdir = $(datadir)/doc/icecast -doc_DATA = admin-interface.html auth.html changes.html faq.html \ - introduction.html relaying.html win32.html basic-setup.html \ - config-file.html glossary.html index.html server-stats.html yp.html -EXTRA_DIST = $(doc_DATA) +# Documentation generation +if HAVE_MKDOCS + +# Directory where the docs will end up +directory = $(top_srcdir)/doc/icecast/ + +EXTRA_DIST += $(directory) + +mkdocs.stamp: + cd "$(top_srcdir)/doc" && $(MKDOCS) build -d "$(directory)" + echo STAMP > mkdocs.stamp + +CLEANFILES = mkdocs.stamp + +install-data-local: + echo FIXMEFIXMEFIXME + exit + $(INSTALL) -d "$(directory)" "$(docdir)" + +uninstall-local: + ( cd "$(directory)"; find . -type f -print0) | (cd "$(docdir)"; xargs -0 rm ) + +all-local: mkdocs.stamp + +clean-local: + rm -rf "$(directory)" + +endif diff --git a/doc/admin-interface.html b/doc/admin-interface.html deleted file mode 100644 index 0df7583347e73d9b3024050929cc99d8236c162d..0000000000000000000000000000000000000000 --- a/doc/admin-interface.html +++ /dev/null @@ -1,143 +0,0 @@ - - - - Icecast Docs Docs — Admin Interface - - - - - - - - -
-

Icecast documentation

-
- -
- -

Icecast 2.4.99.1 Docs — Admin Interface

- -
- -

Overview

-

This section contains information about the admin interface of icecast. Through this interface the user can manipulate many server features. From it you can gather statistics, move listeners from mountpoint to mountpoint, disconnect connected sources, disconnect connected listeners, and many other activities. Each function is enumerated here as well as an example usage of the function.

- -

Each of these functions requires HTTP authentication via the appropriate username and password. For mount-specific functions, you may use either the <admin-username> and <admin-password> specified in the icecast config file, or the username and password specified for that mountpoint (if any). For general functions (not specific to a single mountpoint), you must use the admin username and password. It is also important to note that in all the examples 192.168.1.10 is used as the example host and 8000 is used as the example port for the icecast server.

- -
- -
- -

Admin Functions (mount specific)

-

All these admin functions are mount specific in that they only apply to a particular mountpoint -(as opposed to applying to the entire server). Each of these functions requires a mountpoint to -be specified as input.

- -

Metadata Update

- -

This function provides the ability for either a source client or any external program to update -the metadata information for a particular mountpoint.

- -

Example:
-http://192.168.1.10:8000/admin/metadata?mount=/mystream&mode=updinfo&song=ACDC+Back+In+Black

- -

Fallback Update

-

This function provides the ability for either a source client or any external program to update the -“fallback mountpoint” for a particular mountpoint. Fallback mounts are those that are used in the even -of a source client disconnection. If a source client disconnects for some reason that all currently -connected clients are sent immediately to the fallback mountpoint.

- -

Example:
-http://192.168.1.10:8000/admin/fallbacks?mount=/mystream.ogg&fallback=/myfallback.ogg

- -

List Clients

-

This function lists all the clients currently connected to a specific mountpoint. The results are sent -back in XML form.

- -

Example:
-http://192.168.1.10:8000/admin/listclients?mount=/mystream.ogg

- -

Move Clients (Listeners)

-

This function provides the ability to migrate currently connected listeners from one mountpoint to another. -This function requires 2 mountpoints to be passed in: mount (the from mountpoint) and destination -(the to mountpoint). After processing this function all currently connected listeners on mount will -be connected to destination. Note that the destination mountpoint must exist and have a sounce client -already feeding it a stream.

- -

Example: -http://192.168.1.10:8000/admin/moveclients?mount=/mystream.ogg&destination=/mynewstream.ogg

- -

Kill Client (Listener)

-

This function provides the ability to disconnect a specific listener of a currently connected mountpoint. -Listeners are identified by a unique id that can be retrieved by via the “List Clients” admin function. -This id must be passed in to the request via the variable id. After processing this request, the listener will no longer be -connected to the mountpoint.

- -

Example: -http://192.168.1.10:8000/admin/killclient?mount=/mystream.ogg&id=21

- -

Kill Source

-

This function will provide the ability to disconnect a specific mountpoint from the server. The mountpoint -to be disconnected is specified via the variable mount.

- -

Example: -http://192.168.1.10:8000/admin/killsource?mount=/mystream.ogg

- -
- -
- -

Admin Functions (general)

- -

Stats

-

The stats function provides the ability to query the internal statistics kept by the Icecast server. -Almost all information about the internal workings of the server such as the mountpoints connected, -how many client requests have been served, how many listeners for each mountpoint, etc, are available -via this admin function.
-Note that this admin function can also be invoked via the http://server:port/admin/stats.xml syntax, -however this syntax should not be used and will eventually become deprecated!

- -

Example:
-http://192.168.1.10:8000/admin/stats

- -

List Mounts

-

The list mounts function provides the ability to view all the currently connected mountpoints.

- -

Example: -http://192.168.1.10:8000/admin/listmounts

- -
- -
- -

Web-Based Admin Interface

-

As an alternative to manually invoking these URLs, a web-based admin interface was developed. This -interface provides the same functions that were identified and described above but presents them in -a little nicer way. The web-based admin Interface to Icecast is shipped with Icecast provided in the -admin directory and comes ready to use. All the user needs to do is set the path to this directory -in the config file via the <adminroot> config variable.
-The web-based admin interface is a series of XSLT files which are used to display all the XML obtained -via the URL admin interface. This can be changed and modified to suit the user’s need. Knowledge of -XSLT and transformations from XML to HTML are required in order to make changes to these scripts.

- -

The main URL for the Web-Based Admin Interface is:
-http://192.168.1.10:8000/admin/stats.xsl

- -

From this URL all of the other admin functions can be exercised. -Modification of existing XSLT transforms in /admin is allowed, but new files cannot be created here. -Creation of new XSLT transforms as well as modification of existing transforms is allowed in /web. -These work using the document returned by /admin/stats.xml.
-To see the XML document that is applied to each admin XSLT, just remove the .xsl in your request -(i.e. /admin/listclients). You can then code your XSLT transform accordingly.

- -
- -
- - - - - diff --git a/doc/assets/Makefile.am b/doc/assets/Makefile.am deleted file mode 100644 index e4ef4d11b271a00b96baab8e5c20025663a96fa0..0000000000000000000000000000000000000000 --- a/doc/assets/Makefile.am +++ /dev/null @@ -1,5 +0,0 @@ -## Process this file with automake to produce Makefile.in - -AUTOMAKE_OPTIONS = foreign - -SUBDIRS = css font img diff --git a/doc/assets/css/Makefile.am b/doc/assets/css/Makefile.am deleted file mode 100644 index bdd0a8224ef924816a7de1547c1aad05d5117e19..0000000000000000000000000000000000000000 --- a/doc/assets/css/Makefile.am +++ /dev/null @@ -1,8 +0,0 @@ -## Process this file with automake to produce Makefile.in - -AUTOMAKE_OPTIONS = foreign - -otherdocdir = $(docdir)/assets/css -otherdoc_DATA = style.css - -EXTRA_DIST = $(otherdoc_DATA) diff --git a/doc/assets/css/style.css b/doc/assets/css/style.css deleted file mode 100644 index 7795c5feb584a3195ef33713cb8721c9b467c8df..0000000000000000000000000000000000000000 --- a/doc/assets/css/style.css +++ /dev/null @@ -1,981 +0,0 @@ -@charset "UTF-8"; - -/* Typeface */ -@font-face { - font-family: 'FiraSans'; - font-style: normal; - font-weight: normal; - src: url('../font/FiraSans-Regular.eot'); - src: url('../font/FiraSans-Regular.eot?#iefix') format('embedded-opentype'), url('../font/FiraSans-Regular.woff') format('woff'); -} -@font-face { - font-family: 'FiraSans'; - font-style: italic; - font-weight: normal; - src: url('../font/FiraSans-Italic.eot'); - src: url('../font/FiraSans-Italic.eot?#iefix') format('embedded-opentype'), url('../font/FiraSans-Italic.woff') format('woff'); -} -@font-face { - font-family: 'FiraSans'; - font-style: normal; - font-weight: bold; - src: url('fonts/FiraSans/FiraSans-Bold.eot'); - src: url('../font/FiraSans-Bold.eot?#iefix') format('embedded-opentype'), url('../font/FiraSans-Bold.woff') format('woff'); -} -@font-face { - font-family: 'FiraSans'; - font-style: italic; - font-weight: bold; - src: url('../font/FiraSans-BoldItalic.eot'); - src: url('../font/FiraSans-BoldItalic.eot?#iefix') format('embedded-opentype'), url('../font/FiraSans-BoldItalic.woff') format('woff'); -} -@font-face { - font-family: 'FiraMono'; - font-style: normal; - font-weight: normal; - src: url('../font/FiraMono-Regular.eot'); - src: url('../font/FiraMono-Regular.eot?#iefix') format('embedded-opentype'), url('../font/FiraMono-Regular.woff') format('woff'); -} -@font-face { - font-family: 'FiraMono'; - font-style: normal; - font-weight: bold; - src: url('../font/FiraMono-Bold.eot'); - src: url('../font/FiraMono-Bold.eot?#iefix') format('embedded-opentype'), url('../font/FiraMono-Bold.woff') format('woff'); -} - -/* General */ -*, -*:before, -*:after { - font-family: 'FiraSans', sans-serif; - line-height: 1; - margin: 0; - padding: 0; - border: 0; - -webkit-box-sizing: border-box; - -moz-box-sizing: border-box; - box-sizing: border-box; - -webkit-font-smoothing: antialiased; - -moz-osx-font-smoothing: grayscale; - text-rendering: optimizelegibility; -} -::selection { - background: #9AABB5; - color: #001826; - text-shadow: none; -} -::-moz-selection { - background: #9AABB5; - color: #001826; - text-shadow: none; -} -.hidden { - clip: rect(0 0 0 0); - overflow: hidden; - width: 1px; - height: 1px; - padding: 0; - margin: -1px; - position: absolute; - border: 0; -} - -/* Typography */ -h1, -h2, -h3, -h4 { - line-height: 1.25; -} -h1 { - font-size: 2em; - font-weight: normal; -} -h2 { - font-size: 2em; -} -h3 { - font-size: 1.5em; -} -h4 { - font-size: 1.25em; -} -h5 { - font-size: 1em; - text-transform: uppercase; -} -p, -li, -blockquote, -dl > *, -aside { - line-height: 1.6; - -webkit-hyphens: auto; - -moz-hyphens: auto; - hyphens: auto; -} -blockquote { - font-style: italic; -} -q { - quotes:"\201E" "\201C"; -} -code, -pre { - background-color: #000E17; - color: #9AABB5; - font-family: 'FiraMono', monospace; - line-height: 1.6; -} -code { - word-break: break-all; -} -pre { - white-space: pre-wrap; - padding: 1em; -} -code span, -pre span { - font-family: 'FiraMono', monospace; -} -/* Chrome fix */ -@media screen and (-webkit-min-device-pixel-ratio: 0) { - pre { - word-break: break-all; - } -} -hr { - padding-bottom: 1em; - margin-top: 2em; - clear: both; - border: 0; - border-top: 2px solid #29495C; -} -dt { - font-weight: bold; -} -dd { - margin-left: 1em; -} - -/* Tables */ -table { - width: 100%; - border-collapse: collapse; - border-spacing: 0; -} -th, td { - text-align: left; - line-height: 1.6; - padding: .5em; - vertical-align: top; -} -th { - background-color: #000E17; - text-shadow: 1px 1px 0 rgba(0,0,0,0.5); -} -td { - border: 2px solid #000E17; -} -td a { - word-break: break-all; -} - -/* Inputs */ -::-webkit-input-placeholder { - color: #9AABB5; -} -:-moz-placeholder { - color: #9AABB5; - opacity: 1; -} -::-moz-placeholder { - color: #9AABB5; - opacity: 1; -} -:-ms-input-placeholder { - color: #9AABB5; -} -input::-ms-clear { - display: none; -} -input:not([type="submit"]), textarea { - font: 1em 'FiraMono', monospace -} -input, textarea { - width: 50%; -} -input[type='text'], -input[type='email'], -input[type='password'], -input[type='url'] { - background-color: #000E17; - color: #9AABB5; - display: block; - padding: 1em; -} -input[type='submit'] { - background-color: #001826; - font-size: 1em; - color: #FFFFFF; - display: block; - padding: 1em; - border: 2px solid #29495C; -} -input[type='submit']:hover { - background-color: #29495C; - cursor: pointer; -} -input[type='checkbox'] + label { - display: inline-block !important; - margin: 10px 0 0 10px; -} -form > *:not(:last-child) { - margin-bottom: 1em; -} - -/* Links */ -a:link, -a:visited { - color: #9AABB5; - text-decoration: underline; -} -a:hover, -a:focus, -a:active { - color: #29495C; -} -a.permalink:link, -a.permalink:visited { - text-decoration: none; - display: none; -} -a.permalink:hover, -*:hover > a.permalink { - display: inline-block; - padding-left: .25em; -} - -/* Body */ -body { - background-color: #CAD5DB; - color: #001826; -} -body > * { - margin: 0 auto; -} -body > *:not(:first-child) { - width: 75%; - margin: 0 auto; -} - -/* Header */ -header, -.header { - background-color: #001826; - position: relative; - margin-bottom: 2em; - box-shadow: 0 0 2em rgba(0,0,0,0.5) inset; -} -#xiphbar { - background-color: #666666; - height: 2.25em; - box-shadow: 0 .25em .25em rgba(0,0,0,.5); -} -#xiphbar > div { - width: 75%; - margin: 0 auto; - position: relative; -} -#xiphbar > div > * { - position: absolute; - top: 0.5em; -} -#xiphbar > div > a { - display: block; -} -#xiphbar img { - width: auto; - height: 1.25em; -} -#xiphbar > div > ul { - right: 0; - display: -webkit-box; - display: -moz-box; - display: -ms-flexbox; - display: flex; - flex-direction: row; - list-style: none; -} -#xiphbar li { - font-size: 14px; - margin: 0; -} -#xiphbar li:not(:first-child) { - margin-left: 1em; -} -#xiphbar a:link, -#xiphbar a:visited { - color: #ffcc66; - text-decoration: none; - text-transform: uppercase; - border: none; -} -#xiphbar a:hover, -#xiphbar a:focus { - color: #ffe6b3; -} -#xiphbar a:active { - color: #FFFFFF; -} -header h1, -.header h1 { - color: #29495C; - text-shadow: 1px 1px 0 rgba(0,0,0,0.5); - width: 75%; - padding: 2em 0; - margin: 0 auto; -} -header h1 a:link, -header h1 a:visited, -.header h1 a:link, -.header h1 a:visited { - color: #FFFFFF; - font-weight: bold; - text-decoration: none; - border-bottom: none; -} -header h1 a:hover, -header h1 a:focus, -.header h1 a:hover, -.header h1 a:focus { - text-decoration: underline; -} -header h1 a:active, -.header h1 a:active { - color: #29495C; -} - -/* Navigation */ -nav, -.nav { - margin: 0 auto; - border-top: 2px solid #29495C; - border-bottom: 2px solid #29495C; -} -nav label, -.nav label, -#toggle-nav { - display: none; -} -nav label:before, -.nav label:before { - content: '\2261'; - color: #29495C; - font-size: 4em; - text-shadow: 1px 1px 0 rgba(0,0,0,0.5); - position: absolute; - top: 0.9em; - right: 0.5em; -} -nav label.nobar:before, -.nav label.nobar:before { - top: 0.4em; -} -nav label:hover, -nav label:hover:before, -.nav label:hover, -.nav label:hover:before { - color: #FFFFFF; - cursor: pointer; -} -#toggle-nav:checked + ul { - display: block; -} -nav ul, -.nav ul { - margin: 0 auto; -} -nav ul:before, -nav ul:after, -.nav ul:before, -.nav ul:after { - display: table; - content: ' '; - clear: both; -} -nav li, -.nav li { - display: table-cell; - width: 1%; -} -nav li.on a, -.nav li.on a { - font-weight: bold; -} -nav a:link, -nav a:visited, -.nav a:link, -.nav a:visited { - background-color: #001826; - color: #FFFFFF - ;letter-spacing: 0.1em; - white-space: nowrap; - text-transform: uppercase; - text-decoration: none; - text-align: center; - padding: 1em; - display: block; - border-right: 2px solid #29495C; - border-bottom: none; - position: relative; -} -nav li:last-child a, -.nav li:last-child a { - border-right: none; -} -nav a:after, -.nav a:after { - content: '\0020'; - color: transparent; - width: 100%; - height: 100%; - position: absolute; - top: 0; - left: 0; - opacity: 0; - -ms-filter: "progid:DXImageTransform.Microsoft.Alpha(Opacity=0)"; - filter: alpha(opacity=0); - border: 5px solid #29495C; -} -nav a:focus, -.nav a:focus { - color: #29495C; -} -nav a:hover:after, -nav a:active:after, -nav a:focus:after, -.nav a:hover:after, -.nav a:active:after, -.nav a:focus:after { - opacity: 1; - -ms-filter: none; - filter: none; -} - -/* Content */ -section h2, -.section h2 { - margin-bottom: 1em; -} -section > a:link, -section > a:visited, -.section > a:link, -.section > a:visited { - color: #29495C; -} -section > a:hover, -.section > a:hover { - text-decoration: none; -} -.error { - background-color: #DBCAD5; - color: #5C2949; - padding: .5em 2em; - margin: -1em 0 1em 0; - border: 1px solid #5C2949; -} -.error a { - color: #5C2949; -} -.error a:hover { - text-decoration: none; -} -section > article:not(:last-child), -.section > .article:not(:last-child) { - margin-bottom: 2em; -} -article, -.article { - background-color: #001826; - color: #FFFFFF; - padding: 2em; -} -article h3, -.article h3 { - text-shadow: 1px 1px 0 rgba(0,0,0,0.5); - margin-bottom: 0.7em; - border-bottom: 2px solid #29495C; -} -article h4, -article h5, -.article h4, -.article h5 { - margin-top: 2em; -} -article h3 + h4, -article h3 + h5, -.article h3 + h4, -.article h3 + h5 { - margin-top: 0; -} -article > *:not(:last-child), -.article > *:not(:last-child) { - margin-bottom: 1em; -} -article img, -.article img { - max-width: 100%; -} -article ul, -.article ul { - padding-left: 1em; - margin-top: 1em; -} -article li > ul, -.article li > ul { - margin-top: 0; -} -article nav, -.article .nav { - border-right: 2px solid #29495C; - border-left: 2px solid #29495C; -} -article nav ul, -.article .nav ul { - padding: 0; - margin-top: 0; -} -article aside, -.article .aside { - color: #29495C; - text-align: center; - letter-spacing: 0.1em; - text-transform: uppercase; - padding: 1em 2em 0 2em; - margin: 2em -2em -1em -2em; - border-top: 2px solid #29495C; -} -article aside a:link, -article aside a:visited, -.article .aside a:link, -.article .aside a:visited { - font-weight: bold; - text-decoration: none; -} -.play:link, -.play:visited { - background-color: #000E17; - color: #FFFFFF; - text-decoration: none; - white-space: nowrap; - display: inline-block; - padding: 1em; -} -.play:hover, -.play:active, -.play:focus { - color: #9AABB5; -} -.play span { - font-weight: bold; -} -ul.buttons { - display: -webkit-box; - display: -moz-box; - display: -ms-flexbox; - display: -webkit-flex; - display: flex; - -webkit-flex-flow: row; - flex-direction: row; - -webkit-box-pack: justify; - -moz-box-pack: justify; - -webkit-justify-content: space-between; - -ms-flex-pack: justify; - justify-content: space-between; - padding: 0; - list-style: none; -} -ul.buttons li { - width: 49%; -} -ul.buttons a { - background-color: #000E17; - color: #FFFFFF; - font-size: 1.25em; - font-weight: bold; - text-decoration: none; - display: block; - padding: 1em; -} -ul.buttons a:hover { - text-decoration: underline; -} -ul.buttons .linux { - background: #000E17 url('../img/logo-linux.svg') no-repeat 95% 50%; - background-size: 2em; -} -ul.buttons .windows { - background: #000E17 url('../img/logo-windows.svg') no-repeat 95% 50%; - background-size: 2em; -} -ul.buttons span { - display: inline-block; - margin-top: 1em; -} - -/* Footer */ -footer, -.footer { - text-align: center; - padding: 2em 0; -} -footer a:link, -footer a:visited, -.footer a:link, -.footer a:visited { - color: #29495C; -} - -/* Desktop and tablet */ -@media only screen and (max-width: 1024px) { - #xiphbar > div > a { - text-align: center; - position: static; - padding-top: 0.5em; - } - #xiphbar > div > ul { - display: none; - } - article nav ul:before, - .article .nav ul:before, - nav ul:after, - .nav ul:after { - display: block; - } - article nav li, - .article .nav li { - display: block; - width: auto; - } - article nav a:after, - .article .nav a:after { - border-right: 7px solid #29495C; - border-left: 7px solid #29495C; - } - article nav li:not(:last-child) a, - .article .nav li:not(:last-child) a { - border-right: none; - border-bottom: 2px solid #29495C; - } - ul.buttons { - -webkit-flex-flow: column; - flex-direction: column; - } - ul.buttons li { - width: 100%; - } - ul.buttons li:not(:last-child) { - margin-bottom: 1em; - } -} - -/* Tablet and smartphone */ -@media only screen and (max-width: 768px) { - * { - -ms-text-size-adjust: 100%; - -webkit-text-size-adjust: 100%; - } - input, textarea { - width: 100%; - } - .table-block { - word-break: break-all; - } - .table-block thead { - display: none; - } - .table-block td { - display: block; - } - .table-block tr td:first-child { - font-weight: bold; - padding-bottom: 0; - border-bottom: none; - } - .table-block tr td:last-child { - border-top: none; - } - .table-block tr:not(:last-child) td:last-child { - border-bottom: none; - } - .table-flipscroll { - display: block; - width: 100%; - position: relative; - } - .table-flipscroll:after { - content: ' '; - background-image: -ms-linear-gradient(left, transparent 0%, #001826 100%); - background-image: -moz-linear-gradient(left, transparent 0%, #001826 100%); - background-image: -o-linear-gradient(left, transparent 0%, #001826 100%); - background-image: -webkit-gradient(linear, left top, right top, color-stop(0, transparent), color-stop(1, #001826)); - background-image: -webkit-linear-gradient(left, transparent 0%, #001826 100%); - background-image: linear-gradient(to right, transparent 0%, #001826 100%); - position: absolute; - top: 0; - right: 0; - width: 2em; - height: 100%; - } - .table-flipscroll thead { - display: block; - float: left; - } - .table-flipscroll thead tr { - display: block; - } - .table-flipscroll th { - white-space: nowrap; - text-align: right; - display: block; - border-bottom: 3px solid #000E17; - } - .table-flipscroll tbody { - white-space: nowrap; - display: block; - width: auto; - position: relative; - overflow-x: auto; - } - .table-flipscroll tbody tr { - display: inline-block; - vertical-align: top; - } - .table-flipscroll tbody tr:first-child td { - border-left: none; - } - .table-flipscroll tbody tr:not(:last-child) td { - border-right: none; - } - .table-flipscroll td { - text-align: left; - display: block; - border-bottom: none; - } - .table-flipscroll td:last-child { - border-bottom: 2px solid #000E17; - } - nav, - .nav { - width: auto; - } - nav ul:before, - nav ul:after, - .nav ul:before, - .nav ul:after { - display: block; - } - nav li, - .nav li { - display: block; - width: auto; - } - nav a:after, - nav a:after, - .nav a:after, - .nav a:after { - border-right: 7px solid #29495C; - border-left: 7px solid #29495C; - } - nav li:not(:last-child) a, - .nav li:not(:last-child) a { - border-right: none; - border-bottom: 2px solid #29495C; - } -} - -/* Smartphone */ -@media only screen and (max-width: 450px) { - body > *:not(:first-child) { - width: 100%; - } - #xiphbar > div { - width: 100%; - padding: 0 2em; - } - #xiphbar > div > a { - text-align: left; - } - #xiphbar img { - max-width: 100%; - } - header h1, - .header h1 { - line-height: 1; - padding: 1em; - width: auto; - } - header h1 span, - .header h1 span { - display: none; - } - header nav label, - .header nav label { - display: block; - } - header nav ul, - .header nav ul { - display: none; - } - section h2, - section > p, - .section h2, - .section > p { - padding: 0 1em; - } - .error { - border-right: none; - border-left: none; - } - article > *:not(:first-child):not(.buttons), - .article > *:not(:first-child):not(.buttons) { - text-align: justify; - } - .play { - width: 100%; - } - footer, - .footer { - padding: 2em; - } -} - -/* Print */ -@media print { - * { - background-color: #FFFFFF !important; - color: #000000 !important; - text-shadow: none !important; - text-align: left !important; - border: none; - width: 100% !important; - } - h1, - h2, - h3 { - font-size: 1.25em; - } - h3, - h4 { - page-break-after: avoid; - } - pre { - page-break-inside: avoid; - } - table:after { - display: none; - } - th, - td { - width: auto !important; - border: 1px solid #000000; - } - #xiphbar, - nav, - .nav { - display: none; - } - header, - .header { - box-shadow: none; - margin: 0; - } - article, - .article { - padding: 0 1em; - } - article h3, - .article h3 { - border-bottom: none; - } - article a:after, - .article a:after { - content: ' [' attr(href) ']'; - } - article aside, - .article aside { - text-transform: none; - padding: 0; - margin: 0; - border-top: none; - } -} - -/* Highlight (Solarized Dark) */ -.highlight{background-color:#073642;color:#93a1a1} -.highlight .c{color:#586e75 !important;} -.highlight .cm{color:#586e75 !important;} -.highlight .cp{color:#586e75 !important;} -.highlight .c1{color:#586e75 !important;} -.highlight .cs{color:#586e75 !important;font-weight:bold !important;} -.highlight .err{color:#dc322f !important;background:none !important;} -.highlight .k{color:#cb4b16 !important} -.highlight .o{color:#93a1a1 !important;font-weight:bold !important;} -.highlight .p{color:#93a1a1 !important} -.highlight .ow{color:#2aa198 !important;font-weight:bold !important;} -.highlight .gd{color:#93a1a1 !important;background-color:#372c34 !important;display:inline-block;} -.highlight .gd .x{color:#93a1a1 !important;background-color:#4d2d33 !important;display:inline-block;} -.highlight .ge{color:#93a1a1 !important;} -.highlight .gr{color:#aa0000} -.highlight .gh{color:#586e75 !important;} -.highlight .gi{color:#93a1a1 !important;background-color:#1a412b !important;display:inline-block;} -.highlight .gi .x{color:#93a1a1 !important;background-color:#355720 !important;display:inline-block;} -.highlight .go{color:#888888;} -.highlight .gp{color:#555555;} -.highlight .gs{color:#93a1a1 !important;font-weight:bold !important;} -.highlight .gu{color:#6c71c4 !important;} -.highlight .gt{color:#aa0000;} -.highlight .kc{color:#859900 !important;font-weight:bold !important;} -.highlight .kd{color:#268bd2 !important;} -.highlight .kp{color:#cb4b16 !important;font-weight:bold !important;} -.highlight .kr{color:#d33682 !important;font-weight:bold !important;} -.highlight .kt{color:#2aa198 !important;} -.highlight .n{color:#268bd2 !important;} -.highlight .na{color:#268bd2 !important;} -.highlight .nb{color:#859900 !important;} -.highlight .nc{color:#d33682 !important;} -.highlight .no{color:#b58900 !important;} -.highlight .ni{color:#800080;} -.highlight .nl{color:#859900 !important;} -.highlight .ne{color:#268bd2 !important;font-weight:bold !important;} -.highlight .nf{color:#268bd2 !important;font-weight:bold !important;} -.highlight .nn{color:#b58900 !important;} -.highlight .nt{color:#268bd2 !important;font-weight:bold !important;} -.highlight .nx{color:#b58900 !important;} -.highlight .bp{color:#999999;} -.highlight .vc{color:#008080;} -.highlight .vg{color:#268bd2 !important;} -.highlight .vi{color:#268bd2 !important;} -.highlight .nv{color:#268bd2 !important;} -.highlight .w{color:#bbbbbb;} -.highlight .mf{color:#2aa198 !important;} -.highlight .m{color:#2aa198 !important;} -.highlight .mh{color:#2aa198 !important;} -.highlight .mi{color:#2aa198 !important;} -.highlight .mo{color:#009999;} -.highlight .s{color:#2aa198 !important;} -.highlight .sb{color:#d14;} -.highlight .sc{color:#d14;} -.highlight .sd{color:#2aa198 !important;} -.highlight .s2{color:#2aa198 !important;} -.highlight .se{color:#dc322f !important;} -.highlight .sh{color:#d14;} -.highlight .si{color:#268bd2 !important;} -.highlight .sx{color:#d14;} -.highlight .sr{color:#2aa198 !important;} -.highlight .s1{color:#2aa198 !important;} -.highlight .ss{color:#990073;} -.highlight .il{color:#009999;} -.highlight div .gd,.highlight div .gd .x,.highlight div .gi,.highlight div .gi .x{display:inline-block;width:100%;} diff --git a/doc/assets/font/FiraMono-Bold.eot b/doc/assets/font/FiraMono-Bold.eot deleted file mode 100644 index 80125a8659cd7b0e9009361ceb046cc2e9e0c274..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraMono-Bold.eot and /dev/null differ diff --git a/doc/assets/font/FiraMono-Bold.woff b/doc/assets/font/FiraMono-Bold.woff deleted file mode 100644 index 0e3e6b9fc5c4a0bcf9136eb5b4c1eedcc6e36d3e..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraMono-Bold.woff and /dev/null differ diff --git a/doc/assets/font/FiraMono-Regular.eot b/doc/assets/font/FiraMono-Regular.eot deleted file mode 100644 index 283b4705693b889875acd44cbc70c664bbf29fbb..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraMono-Regular.eot and /dev/null differ diff --git a/doc/assets/font/FiraMono-Regular.woff b/doc/assets/font/FiraMono-Regular.woff deleted file mode 100644 index 5aac32401393b3832636351f5d008d786fb77504..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraMono-Regular.woff and /dev/null differ diff --git a/doc/assets/font/FiraSans-Bold.eot b/doc/assets/font/FiraSans-Bold.eot deleted file mode 100644 index 07323b6054331b4ea18975a33fed4dc69b331289..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraSans-Bold.eot and /dev/null differ diff --git a/doc/assets/font/FiraSans-Bold.woff b/doc/assets/font/FiraSans-Bold.woff deleted file mode 100644 index ebc183ee91db04e7ebe346296ab6565acd74b9ca..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraSans-Bold.woff and /dev/null differ diff --git a/doc/assets/font/FiraSans-BoldItalic.eot b/doc/assets/font/FiraSans-BoldItalic.eot deleted file mode 100644 index 1600c30ceff2cd0e1188ecdfc9f62553cf621180..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraSans-BoldItalic.eot and /dev/null differ diff --git a/doc/assets/font/FiraSans-BoldItalic.woff b/doc/assets/font/FiraSans-BoldItalic.woff deleted file mode 100644 index 51b9f839f9fa7494ec492445c4fff8cfa1150507..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraSans-BoldItalic.woff and /dev/null differ diff --git a/doc/assets/font/FiraSans-Italic.eot b/doc/assets/font/FiraSans-Italic.eot deleted file mode 100644 index 1369626eaf023301ec12870f330ea524684b269c..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraSans-Italic.eot and /dev/null differ diff --git a/doc/assets/font/FiraSans-Italic.woff b/doc/assets/font/FiraSans-Italic.woff deleted file mode 100644 index e27b7f3bb3263440d79cbb4834d9be0026844811..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraSans-Italic.woff and /dev/null differ diff --git a/doc/assets/font/FiraSans-Regular.eot b/doc/assets/font/FiraSans-Regular.eot deleted file mode 100644 index ab82a33938f23171f89ee0e70ffa24b23a0851da..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraSans-Regular.eot and /dev/null differ diff --git a/doc/assets/font/FiraSans-Regular.woff b/doc/assets/font/FiraSans-Regular.woff deleted file mode 100644 index 0a82f0a1e85a99d723bb9408f0f3220585ff89c3..0000000000000000000000000000000000000000 Binary files a/doc/assets/font/FiraSans-Regular.woff and /dev/null differ diff --git a/doc/assets/font/Makefile.am b/doc/assets/font/Makefile.am deleted file mode 100644 index 0f6362a7db9e6aaca3592471070abef3625d98f9..0000000000000000000000000000000000000000 --- a/doc/assets/font/Makefile.am +++ /dev/null @@ -1,13 +0,0 @@ -## Process this file with automake to produce Makefile.in - -AUTOMAKE_OPTIONS = foreign - -otherdocdir = $(docdir)/assets/font -otherdoc_DATA = FiraMono-Bold.eot FiraMono-Regular.eot \ - FiraSans-Bold.eot FiraSans-BoldItalic.woff \ - FiraSans-Italic.eot FiraSans-Regular.eot \ - FiraMono-Bold.woff FiraMono-Regular.woff \ - FiraSans-BoldItalic.eot FiraSans-Bold.woff \ - FiraSans-Italic.woff FiraSans-Regular.woff - -EXTRA_DIST = $(otherdoc_DATA) diff --git a/doc/assets/img/Makefile.am b/doc/assets/img/Makefile.am deleted file mode 100644 index 145b5f7abb2d9ecfef2fc82fa7fc2ad693fbc711..0000000000000000000000000000000000000000 --- a/doc/assets/img/Makefile.am +++ /dev/null @@ -1,8 +0,0 @@ -## Process this file with automake to produce Makefile.in - -AUTOMAKE_OPTIONS = foreign - -otherdocdir = $(docdir)/assets/img -otherdoc_DATA = xiph-community.svg - -EXTRA_DIST = $(otherdoc_DATA) diff --git a/doc/assets/img/xiph-community.svg b/doc/assets/img/xiph-community.svg deleted file mode 100644 index a0c61669e529f512e6b2d4a2b843bc28996fc821..0000000000000000000000000000000000000000 --- a/doc/assets/img/xiph-community.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - logo + the xiph open source - Created with Sketch. - - - - - - - - \ No newline at end of file diff --git a/doc/auth.html b/doc/auth.html deleted file mode 100644 index 9ed12e440b3c50fe78bb6d7d7ff417bfe757b0f8..0000000000000000000000000000000000000000 --- a/doc/auth.html +++ /dev/null @@ -1,359 +0,0 @@ - - - - Icecast Docs Docs — Authentication - - - - - - - - -
-

Icecast documentation

-
- -
- -

Icecast 2.4.99.1 Docs — Authentication

- -
-

Listener Authentication

-

Listener authentication is a feature of Icecast which allows you to secure a certain mountpoint such that in order to listen, -a listener must pass some verification test. With this feature, a simple pay-for-play operation (eg. user/pass), or some filtering -based on the listener connection can be performed. This section will show you the basics of setting up and maintaining this component.

- -

To define listener authentication, a group of tags are specified in the <mount> group relating to the mountpoint. This means -that authentication can apply to listeners of source clients or relays.

- -

The following authentication mechanisms can apply to listeners:

- - - -

The listener authentication within a specified mount in the icecast XML configuration can apply to either to a stream from a -source client, relay or a webroot based file. They do apply to intro files or fallback streams.

- -
- -
-

htpasswd Listener Authentication

-

In order to use listener authentication, you must configure a mount specific option. This means that you have to provide -a <mount> section in the main icecast config file. The following is an example:

- -
<mount>
-	<mount-name>/example.ogg</mount-name>
-	<authentication type="htpasswd">
-		<option name="filename" value="myauth"/>
-		<option name="allow_duplicate_users" value="0"/>
-	</authentication>
-</mount>
- -

To support listener authentication you must provide at a minimum <mount-name> and <authentication>.
-The mount-name is the name of the mountpoint that you will use to connect your source client with and authentication configures -what type of Icecast authenticator to use.
-Currently, only htpasswd and url are implemented. Each authenticator has a variable number of options that are required and -these are specified as shown in the example.
-The htpasswd authenticator requires a few parameters:
-The first, filename, specifies the name of the file to use to store users and passwords. Note that this file need not exist -(and probably will not exist when you first set it up).
-Icecast has built-in support for managing users and passwords via the web admin interface. More on this later in this section.
-The second option, allow_duplicate_users, if set to 0, will prevent multiple connections using the same username. Setting this -value to 1 will enable mutltiple connections from the same username on a given mountpoint.
-Note there is no way to specify a “max connections” for a particular user.

- -

Icecast supports a mixture of streams that require listener authentication and those that do not.

- -

Configuring Users and Passwords

-

Once the appropriate entries are made to the config file, connect your source client (using the mountpoint you named in -the config file). To configure users and passwords for this stream you must use the web-based admin interface. Navigate to -http://server:ip/admin/stats.xsl to begin. If you have configured everything properly, you should see a screen like the -following:

- -

Screenshot of Admin Stats

- -

You will see a lock in front of all mountpoint configured for listener authentication. Also note that this page will -only show connected mountpoints.

- -

To manage users and passwords for this mountpoint, click on the “Manage Authentication” link. The following screen will be shown:

- -

Screenshot of Manage Authentication

- -

This screen will show all the users configured for this mountpoint. Adding users is as simple as entering a username and password -in the fields and clicking “Add”.
-Note that usernames must be unique and there are no restrictions on passwords. You can delete users by clicking the appropriate -delete link next to each user.

- -

Finishing it all off

-

Ok, so you’ve created your users, and you have everything setup properly, how do your users login? Well, we’ve provided a simple login -form that you can use for this purpose. This page (http://server:port/auth.xsl) will bring up a form that users can use to enter their -username and password.

- -

Screenshot of Auth Page

- -

This page will serve a m3u with the username and password and in most cases should open the correct media player and begin playing -your stream.

- -
- -
-

URL

- -

Authenticating listeners via the URL method involves Icecast, when a listener connects, issuing requests to a web server -and checking the response headers. If a certain header is sent back then the listener connecting is allowed to continue, -if not, an error is sent back to the listener.

- -

The URLs specified will invoke some web server scripts like PHP to do any work that they may choose to do. All that is -required of the scripting language is that POST information can be handled and response headers can be sent back.
-libcurl is used for the requesting so https connections may be possible, but be aware of the extra overhead involved.

- -

The useragent sent in each curl request will represent the Icecast server version. The response headers will depend on -whether the listener is to be accepted. In the case of rejection, a response header
-Icecast-Auth-Message: Reason
-should also be returned for placing in the log files.

- -

In order to use URL based listener authentication, you must configure a mount specific option. This means that you -have to provide a <mount> section in the main Icecast 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://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://auth.example.org/source.php"/>
-    </authentication>
-</mount>
- -

The options are described below in more detail, each of which is optional, but in each case, within the POST data, -the value for each setting is encoded.

- -

mount_add

- -

This URL is for informing the auth server of a stream starting. No listener information is passed for this, -but it can be used to initialise any details the auth server may have.

- -
POST Details
-
-
action
-
mount_add
-
mount
-
the mountpoint starting up
-
server
-
the server name (<hostname>)
-
port
-
the server port
-
- -
Example
-

action=mount_add&mount=/live&server=icecast.example.org&port=8000

- -

mount_remove

-

This URL is for informing the auth server of a stream finishing, like the start option, no listener details -are passed.

- -
POST Details
-
-
action
-
mount_remove
-
mount
-
the mountpoint being removed
-
server
-
the server name (<hostname>)
-
port
-
the server port
-
- -
Example
-

action=mount_remove&mount=/live&server=icecast.example.org&port=8000

- -

listener_add

-

This is most likely to be used if anything. When a listener connects, before anything is sent back to them, this -request is processed. The default action is to reject a listener unless the auth server sends back a response header -which may be stated in the header option.

- -
POST Details
-
-
action
-
listener_add
-
mount
-
the mountpoint, including query parameters
-
server
-
the server name (<hostname>)
-
port
-
the server port
-
user
-
user as stated in listener HTTP basic auth
-May be blank
-
pass
-
pass as stated in listener HTTP basic auth -May be blank
-
client
-
unique ID for the client within Icecast
-
ip
-
listeners IP address
-
agent
-
useragent from the listeners player
-
- -

Note: The mount here (unlike the start/end options) states the requested url including any query parameters, -so for instance the requested URL can be /stream.ogg&session=xyz, but note that each option data is -escaped before being passed via POST.

- -
Example
-

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

- -

listener_remove

-

This URL is for when a listener connection closes.

- -
POST Details
-
-
action
-
listener_remove
-
mount
-
the mountpoint
-
server
-
the server name (<hostname>)
-
port
-
the server port
-
user
-
user as stated in listener HTTP basic auth
-May be blank
-
pass
-
pass as stated in listener HTTP basic auth -May be blank
-
client
-
unique ID for the client within Icecast
-
ip
-
listeners IP address
-
agent
-
useragent from the listeners player
-
duration
-
number of seconds the listener was connected for
-
- -
Example
-

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

- -

stream_auth

-

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.

- -
POST Details
-
-
action
-
stream_auth
-
mount
-
the mountpoint
-
server
-
hostname of the Icecast server the client tries to connect to
-
port
-
the port of said server
-
user
-
username as sent by the source client
-
pass
-
password as sent by the source client
-
admin
-
admin request (read below)
-
- -

Note: As admin requests can come in for a stream (eg. metadata update) these requests can be issued while -stream is active. For these admin is set to 1 in POST details.

- -
Example
-

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

- -

Other Options

- -
-
auth_header
-
The expected response header to be returned that allows the authencation to take place may be specified here.
-The default is:
-icecast-auth-user: 1
-but it could be anything you like, for instance:
-HTTP 200 OK
-
timelimit_header
-
Listeners could have a time limit imposed on them, and if this header is sent back with a figure (which represents seconds) -then that is how long the client will remain connected for.
-
headers
-
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 sent as POST parameters.
-
header_prefix
-
This is the prefix used for passing client headers. See headers for details.
-
- -
- -
-

A note about players and authentication

-

We do not have an exaustive list of players that support listener authentication.
-We use standard HTTP basic authentication, and in general, many media players support this if they support anything at all. -Winamp and Foobar2000 support HTTP basic authentication on Windows, and XMMS supports it on UNIX platforms. Winamp/XMMS at -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
-
-
action
-
stream_auth
-
mount
-
the mountpoint
-
server
-
hostname of the Icecast server the client tries to connect to
-
port
-
the port of said server
-
user
-
username as sent by the source client
-
pass
-
password as sent by the source client
-
admin
-
admin request (read below)
-
- -

Note: As admin requests can come in for a stream (eg. metadata update) these requests can be issued while -stream is active. For these admin is set to 1 in POST details.

- -
Example
-

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

- -
- -
- - - - - diff --git a/doc/basic-setup.html b/doc/basic-setup.html deleted file mode 100644 index 95dc25a6496b14b666d10193ea46034e7bba430d..0000000000000000000000000000000000000000 --- a/doc/basic-setup.html +++ /dev/null @@ -1,91 +0,0 @@ - - - - Icecast Docs Docs — Basic Setup - - - - - - - - -
-

Icecast documentation

-
- -
- -

Icecast 2.4.99.1 Docs — Basic Setup

- -
-

Basic Requirements

-

This section will describe the essential requirements in setting up a simple Internet radio station. It is by no means a complete list but should give you enough to get started. Please also note that those are generic instructions. If you installed a Linux/Unix distribution package, then it will likely come with different paths, different means of starting it, etc. In that case please also refer to the documentation of that distribution and or a distribution specific How-To.

- -

There are two major components involved: the streaming server (Icecast in this case) and the source client.
-The Icecast server will be the place where all listeners of your station will connect. The source client (in general) runs on a separate machine than Icecast, but does not necessarily need to. Source clients send the content to Icecast and provide the stream data (encoded audio) that is then relayed out to listeners by Icecast.

- -

It is important to note that not all source clients work with Icecast 2. You will need to check to make sure that Icecast 2 is supported by your chosen source client.

- -
- -
-

The Basics

- -

Each Icecast server can house multiple broadcasts (or mountpoints) each containing a separate stream of content. A ‘mountpoint’ is a unique name on your server identifying a particular stream - it looks like a filename, such as ‘/stream.ogg’. A listener can only listen to a single mountpoint at a time. This means you can have a single Icecast server contain either multiple broadcasts with different content, or possibly the same broadcast but with streams of different bitrates or qualities. In this case each broadcast or stream is a separate mountpoint.

- -

At this point, the steps outlined here related to the Unix version or Win32 console version of Icecast. Icecast is also available in a Win32 GUI version, and the steps are similar in setup, but not quite the same.

- -

The first step in the process is to find and install the Icecast2 server itself. How to do this is not contained within this documentation. After installation you should have and Icecast binary and 3 directories

- - - -

The next step is to edit the icecast.xml file and set the appropriate values. Most of the specified values in the samples are fine, for a basic setup the following entries should be specified, and if neccessary, changed to suite your situation:

- -

<hostname> - DNS name or IP address used for stream directory listings.
-<source-password> - Will be used for the source client authentication.
-<admin-password> - Will be used for authenticating admin features of Icecast.
-<listen-socket> (both port and bind-address)

- -

Once the configuration file is modified, you should be able to start the server with the following command

- -
icecast -c /path/to/icecast.xml
-
- -

If no error messages are generated, then check the error.log file for the ‘server started’ message, it will look something like :

- -
[2003-10-31  13:04:49] INFO main/main.c Icecast 2.3.0 server started
-
- -

You may notice slight variations to the line above, the time will no doubt be different, and on some platforms the main.c is just main, but the key thing here is that the server is started, logging is working and the version is shown.

- -

You can also verify that it started by visiting the following URL: http://yourip:port/admin/stats.xml. You should be prompted for a username and password. Enter the username admin and the password you entered for <admin-password>. If all is well, you should see an small XML tree which represents Icecast statistics (more about that later).

- -

Now that the Icecast server is started you must now configure your source client. The information you will need for the source client is the following:

- -

IP address and Port of the icecast server - both of these come from <listen-socket>
-source password - from <source-password>

- -

Additionally, you will need to choose a mountpoint and specify this in the source client. Icecast does not need to know about each mount point (although you can configure settings for specific mountpoint - this is covered under Advanced configuration) there are, however, some points to mention regarding mountpoints. All Ogg Vorbis streams should have mountpoints that end in .ogg (i,e. /mystream.ogg). This is due to the lazy way most media players infer the type of stream. MP3 streams usually do not contain an extension (/mystream). Mount points also should not contain any spaces or odd characters (again due to the lazy way many of the media players are coded).

- -

Once you have configured your source client, you should be able to connect it to the Icecast server. Verify that it is connected by hitting the stats.xml URL that was mentioned above.

- -

Now that you have the source connnected, listening to the stream involves simply opening the appropriate following URL in a browser: http://yourip:port/mounpoint-you-specified. So, for instance, if you attached your source client to an icecast server located at 192.0.2.23:8000 with a mountpoint of /mystream.ogg, then you would open: http://192.0.2.23:8000/mystream.ogg or http://192.0.2.23:8000/mystream.ogg.m3u. Note that the URL with .m3u extention will serve up a link that opens most media players. Also it is important to note that m3u need not contain only MP3 stream, it can contain streams of arbitrary content-type and is used by Icecast to serve a playlist that represents your broadcast to listening clients. Alternatively you can open up the stream URL directly within your media player (http://192.0.2.23:8000/mystream.ogg in this case)

-
- - -
- - - - - diff --git a/doc/changes.html b/doc/changes.html deleted file mode 100644 index afb3c585de4eb5a05fb5d4faa102bfe621ab3ac0..0000000000000000000000000000000000000000 --- a/doc/changes.html +++ /dev/null @@ -1,149 +0,0 @@ - - - - Icecast Docs Docs — Changes - - - - - - - - -
-

Icecast documentation

-
- -
- -

Icecast 2.4.99.1 Docs — Changes

- - -
-

Version 2.4.99.1

- - - -
-

Version 2.4.1

- -

Fixes

- -
    -
  • Fixed cross-corruption of file descriptors by on-connect/on-disconnect scripts, specifically STDIN, STDOUT and STDERRR vs TCP connections. -
      -
    • We actually close not just 0, 1 and 2, but the first 1024 FDs, which seems common trade-off practice, but still not ideal. A more thorough fix will need platform specific logic and significant work.
    • -
    • The STDIN/OUT/ERR problem is fixed reliably, but other problems could occur if both the script and the server use FDs >1024 at the same time
    • -
    • This is now reasonably safe, but care should be exercised nevertheless.
    • -
    -
  • -
  • Disabled SSLv3 and SSL compression explicitly to improve security
  • -
  • Updated the default ciphers to be more secure
  • -
  • Fixed JSON status API problems -
      -
    • Put the XSLT last item check into every filtered tag.
    • -
    • This way we shouldn’t run into problems of this type anymore.
    • -
    • Also it should be easier to customize the XSLT this way, if someone wants to filter differently.
    • -
    -
  • -
  • Fixed <auth> in <mount type="default"> to work properly.
  • -
  • Fixed listener connection duration logging in access.log. Regression was introduced for only some platforms by an earlier security fix.
  • -
  • Fixed time zone reporting in _iso8601 fields on Windows.
  • -
  • added warnings on empty and default values of <fileserve>, <hostname>, <location>, <admin> and <server-id>
  • -
  • send errorlog (loglevel WARN) to stderr prior to opening logfiles.
  • -
  • Fixed handling of empty strings in config file. Now empty strings are handled in: accesslog, errorlog, logdir, webroot, adminroot and hopefully all kinds of port.
  • -
  • Be more verbose in case of fileserve off. People disable fileserve and then wonder why the web interface CSS breaks.
  • -
  • More details in log messages -
      -
    • Add source IP adress to startup and source exit logging
    • -
    • Add mountpoint to some log lines
    • -
    -
  • -
  • Updated the config file to avoid common pitfalls and make some things more obvious.
  • -
  • Fixed some compiler warnings
  • -
  • Fixed autogen.sh to work properly on Mac OS
  • -
  • Fixed JSON access by adding support for global and mount specific custom HTTP headers. -
      -
    • The purpose is to fix JSON access from browsers, by supporting basic CORS use cases. This is both important for some HTML5 <audio> or <video> use cases and accessing the JSON status API.
    • -
    • The default icecast config contains the very permissive global header: <header name="Access-Control-Allow-Origin" value="*" />
    • -
    -
  • -
- -

Known issues

- -
    -
  • HTTP PUT implementation currently doesn’t support chunked encoding yet.
  • -
  • HTTP PUT with “Expect: 100-Continue” receives first a “100” and soon after a “200”, instead of the “200” at the end of transmission.
  • -
  • Caution should be exercised when using <on-connect> or <on-disconnect>, as there is a small chance of stream file descriptors being mixed up with script file descriptors, if the FD numbers go above 1024. This will be further addressed in the next Icecast release.
  • -
  • Don’t use comments inside <http-headers> as it will prevent processing of further <header> tags.
  • -
-
- -
-

Version 2.4.0

- -

New Features

- -
    -
  • Support for Ogg Opus streams
  • -
  • Support for WebM streams
  • -
  • HTTP 1.1 PUT support for source connections. Deprecating SOURCE method
  • -
  • Default mount
    -This allows you to define a global set of defaults for ALL mounts. This way you can use e.g. url-auth for sources and or listeners also for dynamically generated mounts.
  • -
  • Web interface redone -
      -
    • Web output properly redone, credit to ePirat
    • -
    • Added <audio> element for supported audio streams
    • -
    • Now validates completely as XHTML1.0 strict
    • -
    • Also improves rendering on mobile devices
    • -
    -
  • -
  • Added basic JSON API (/status-json.xsl) based on a xml2json template by Doeke Zanstra (see xml2json.xslt). Output is roughly limited to data also visible through status.xsl
  • -
  • Send charset in HTTP headers for everything, excluding file-serv and streams
  • -
  • Allow (standard strftime(3)) %x codes in <dump-file>. Disabled for Win32
  • -
  • Added stream_start_iso8601, server_start_iso8601 to statitics. ISO8601 compliante timestamps for statistics. Should make usage in e.g. JSON much easier. Added as new variables to avoid breaking backwards compatibility
  • -
  • Now compiles for Win32 using mingw
  • -
  • Added options headers and header_prefix to URL based listener auth
  • -
  • Updated listener_remove handler, added ip= and agent=
  • -
  • Allow full URLs to be returned by the master server
  • -
- -

Fixes

- -
    -
  • Security fix: Override supplementary groups if is used
  • -
  • Fixes for some race conditions
  • -
  • Dropped debian packaging directory as debian use their own.
  • -
  • Send proper HTTP headers in responses to clients.
  • -
  • Corrected Content-Length: header in admin (raw) requests. Thanks to paluh for reporting.
  • -
  • Escape log entries in access log
  • -
  • Fixed a memory leak. Lost headers of stream because of wrong ref counter in associated refbuf objects.
  • -
  • Avoid memory leak in _parse_mount() when type-attribute is set
  • -
  • Updated web interface to be XHTML compliant.
  • -
  • Removed status2.xsl from release. It was only a broken example file anyway.
  • -
- -

Known issues

- -
    -
  • Will crash if certain config tags are left empty
  • -
- -
- -
- -
- - - - - \ No newline at end of file diff --git a/doc/config-file.html b/doc/config-file.html deleted file mode 100644 index 039661bd520068c3e8e561d021321ac2a58ba204..0000000000000000000000000000000000000000 --- a/doc/config-file.html +++ /dev/null @@ -1,783 +0,0 @@ - - - - Icecast Docs Docs — Config File - - - - - - - - -
-

Icecast documentation

-
- - -
- -

Icecast 2.4.99.1 Docs — Config File

- - -
-

Overview

-

This section will describe each section of the config file and is grouped into the following sections:

- - - -
- -
-

A word of warning

-

Please note that, especially for new Icecast users, editing the config file can be quite tricky. -It is thus recommended to make a backup of the original config file and then start by just changing all -passwords, nothing else. You can then use the source-password to bring up an initial stream and get more -comfortable with how Icecast works.

- -

Should you need to customize the configuration, then make a backup of your working config file, before you -make any changes. If Icecast refuses to start it is in most cases due to a malformed config file. In such a -case running the following command should point out most XML syntax problems.

- -
xmllint icecast.xml
-
- -

Also check the Icecast error.log for additional hints in case of all problems!

- -
- -
-

Limits

- -
<limits>
-    <clients>100</clients>
-    <sources>2</sources>
-    <queue-size>102400</queue-size>
-    <client-timeout>30</client-timeout>
-    <header-timeout>15</header-timeout>
-    <source-timeout>10</source-timeout>
-    <burst-on-connect>1</burst-on-connect>
-    <burst-size>65536</burst-size>
-</limits>
- -

This section contains server level settings that, in general, do not need to be changed. -Only modify this section if you know what you are doing.

- -
-
clients
-
Total number of concurrent clients supported by the server. Listeners are considered clients, -but so are accesses to any static content (i.e. fileserved content) and also any requests to -gather stats. These are max concurrent connections for the entire server (not per mountpoint).
-
sources
-
Maximum number of connected sources supported by the server. This includes active relays and source clients
-
queue-size
-
This is the maximum size (in bytes) of the stream queue. A listener may temporarily -lag behind due to network congestion and in this case an internal queue is maintained for the -listeners. If the queue grows larger than this config value, then it is truncated and any listeners -found will be removed from the stream. This will be the default setting for the streams which is -512k unless overridden here. You can override this in the individual mount settings which can be -useful if you have a mixture of high bandwidth video and low bitrate audio streams.
-
client-timeout
-
This does not seem to be used.
-
header-timeout
-
The maximum time (in seconds) to wait for a request to come in once the client has made a connection -to the server. In general this value should not need to be tweaked.
-
source-timeout
-
If a connected source does not send any data within this timeout period (in seconds), -then the source connection will be removed from the server.
-
burst-on-connect
-
This setting is really just an alias for burst-size. When enabled the burst-size is 64 kbytes and -disabled the burst-size is 0 kbytes. This option is deprecated, use burst-size instead.
-
burst-size
-
The burst size is the amount of data (in bytes) to burst to a client at connection time. Like burst-on-connect, -this is to quickly fill the pre-buffer used by media players. The default is 64 kbytes which is a typical size used by -most clients so changing it is not usually required. This setting applies to all mountpoints unless overridden in -the mount settings. Ensure that this value is smaller than queue-size, if necessary increase queue-size to be larger -than your desired burst-size. Failure to do so might result in aborted listener client connection attempts, due to -initial burst leading to the connection already exceeding the queue-size limit.
-
- -
- -
-

Authentication

- - -
<authentication>
-    <source-password>hackme</source-password>
-    <relay-user>relay</relay-user>
-    <relay-password>hackme</relay-password>
-    <admin-user>admin</admin-user>
-    <admin-password>hackme</admin-password>
-</authentication>
- - -

This section contains all the usernames and passwords used for administration purposes or to connect sources and relays.

- - -
-
role
-
contains role definitions
-
- - -
-
source-password
-
The unencrypted password used by sources to connect to Icecast. The default username for all -source connections is ‘source’ but this option allows to specify a default password. This and the -username can be changed in the individual mount sections.
-
- - -
-
relay-user
-
Used in the master server as part of the authentication when a slave requests the list of streams -to relay. The default username is relay
-
- - -
-
relay-password
-
Used in the master server as part of the authentication when a slave requests the list of streams to relay.
-
- - -
-
admin-user/admin-password
-
The username/password used for all administration functions. This includes retrieving statistics, accessing the web-based -administration screens, etc. A list of these functions can be found in the “Administration” section of the manual.
-
- -
- -
-

Stream Directory Settings

- -
<directory>
-    <yp-url-timeout>15</yp-url-timeout>
-    <yp-url>http://dir.xiph.org/cgi-bin/yp-cgi</yp-url>
-</directory>
- -

This section contains all the settings for listing a stream on any of the Icecast YP Directory servers. -Multiple occurances of this section can be specified in order to be listed on multiple directory servers.

- -
-
yp-url-timeout
-
This value is the maximum time Icecast will wait for a response from a particular directory server. -The recommended value should be sufficient for most directory servers.
-
yp-url
-
The URL which Icecast uses to communicate with the Directory server. -The value for this setting is provided by the owner of the Directory server.
-
- -
- -
-

Misc Server Settings

- -

Server wide settings

- -
<hostname>localhost</hostname>
-<location>earth</location>
-<admin>icemaster@localhost</admin>
-<fileserve>1</fileserve>
-<server-id>icecast 2.5</server-id>
- -
-
hostname
-
This is the DNS name or IP address that will be used for the stream directory lookups or -possibily the playlist generation if a Host header is not provided. While localhost is shown as -an example, in fact you will want something that your listeners can use.
-
location
-
This sets the location string for this Icecast instance. It will be shown e.g in the web interface.
-
admin
-
This should contain contact details for getting in touch with the server administrator. -Usually this will be an email address, but as this can be an arbitrary string it could also -be a phone number. This will be shown e.g. in the web interface.
-
fileserve
-
This flag turns on the icecast2 fileserver from which static files can be served. All files -are served relative to the path specified in the <paths><webroot> configuration setting. -By default the setting is enabled so that requests for the static files needed by the status -and admin pages, such as images and CSS are retrievable.
-
server-id
-
This optional setting allows for the administrator of the server to override the default -server identification. The default is icecast followed by a version number and most will -not care to change it however this setting will allow this. It is not recommended to use this -setting, unless you have very good reasons and know what you are doing.
-
- -
- -
-

TCP Port settings

- -

The following shows how you can specify the listening settings for the server.

- -

Generic port setup

- -

The first shows an example of a common and simple way to define a listening socket:

- -
<listen-socket>
-    <port>8000</port>
-</listen-socket>
- -

Using this as a basis we can extend this with an <bind-address> setting to limit which address Icecast -will listen on. Most will not need to use bind-address and often get confused by using it when there is -no need. Another possibility is to use an <ssl> boolean setting which informs Icecast that a secured -connection is to be used. A common use for using a secure connection would be for admin page access.

- -

Backward compatibility with Shoutcast source clients

- -

The following shows how we can extend a single listen-socket to work with Shoutcast style source clients. -There are two issues shoutcast source clients have over icecast source clients, one is the lack of mountpoint -and the second is the requirement of two ports. Both of these issues are handled by a simple addition in -the listen-socket.

- -
<listen-socket>
-    <port>8000</port>
-    <shoutcast-mount>/live.mp3</shoutcast-mount>
-</listen-socket>
- -

As before the port specified is allocated but this time the shoutcast-mount implicity defines a second -listening socket whose port number is always one higher than the port defined, this also informs icecast -of which mountpoint the shoutcast source client on this socket will be using. Using this approach you can -allow multiple shoutcast source clients to connect at the same time.

- -

Old style Shoutcast source client compatible setup (deprecated)

- -

The following is just to show the longer approach to defining shoutcast compatability.

- -
<shoutcast-mount>/live.nsv</shoutcast-mount>
-<!-- You may have multiple <listen-socket> elements -->
-<listen-socket>
-    <port>8000</port>
-</listen-socket>
-
-<listen-socket>
-    <port>8001</port>
-    <shoutcast-compat>1</shoutcast-compat>
-</listen-socket>
- -

Note that multiple listen-socket sections may be configured in order to have Icecast listen on multiple network -interfaces or multiple ports. If a bind-address is not specified for a particular listen-socket, then the socket -will be bound to all interfaces (including IPv6 if available). For most people, the bind-address option will not -be required and often confuses people.

- -
-
port
-
The TCP port that will be used to accept client connections.
-
bind-address
-
An optional IP address that can be used to bind to a specific network -card. If not supplied, then it will bind to all interfaces.
-
ssl
-
If set to 1 will enable HTTPS on this listen-socket. Icecast must have been compiled against openSSL to be able to do so.
-
shoutcast-mount
-
An optional mountpoint setting to be used when shoutcast DSP compatible clients connect. The default global setting -is /stream but can be overridden here to use an alternative name which may include an extension that some clients -require for certain formats.
-Defining this within a listen-socket group tells Icecast that this port and the subsequent port are to be used for -Shoutcast compatible source clients. This is an alternative to the shoutcast-compat approach as this implicitly -defines the second listening socket and allows for specifying multiple sockets using different mountpoints for -shoutcast source clients. The shoutcast-mount outside of a listen-socket group is the global setting of the -mountpoint to use.
-
shoutcast-compat
-
This optional flag will indicate that this port will operate in Shoutcast compatibility mode. Due to major differences -in the source client connection protocol, if you wish to use any of the shoutcast DJ tools, you will need to configure -at least one socket as shoutcast-compatible. Note that when in this mode, only source clients (and specifically shoutcast -source clients) will be able to attach to this port. All listeners may connect to any of the ports defined without this flag. -Also, for proper Shoutcast DSP compatibility, you must define a listen socket with a port one less than the one defined as -shoutcast-compat. This means if you define 8001 as shoutcast-compat, then you will need to define a listen port -of 8000 and it must not also be defined as shoutcast-compat. See the example config file in the distribution for more info.
-
- -
- -
-

Global HTTP headers

- -
<http-headers>
-    <header name="Access-Control-Allow-Origin" value="*" />
-    <header name="X-Robots-Tag" value="index, noarchive" />
-    <header name="foo" value="bar" status="200" />
-    <header name="Nelson" value="Ha-Ha!" status="404" />
-</http-headers>
- -

Icecast can be configured to send custom HTTP headers. This is available as a global setting and inside mountpoints. This section explains the global settings.

- -

This functionality was introduced mainly to enable the use of simplified cross-origin resource sharing. The Icecast default configuration contains the first header, as seen in the above exmple, for this reason.

- -
-
http-headers
-
This element is placed anywhere inside the main section of the Icecast config. It will contain <header> child elements, that specify the actual headers one by one.
-
header
-
This tag specifies the actual header to be sent to a HTTP client in response to every request. -This tag can contain the following attributes: - -
    -
  • name is required and its value specifies the HTTP header field name.
  • -
  • value is required and its value specifies the HTTP header field value.
  • -
  • status is optional and limits sending the header to certain HTTP status codes. If not specified, the default is to return the header for every HTTP status code. This attribute is only available for global headers, at the moment.
  • -
-
-
- -

At the moment only global headers will be sent in case the HTTP status is not “200”. This is subject to change in the future. -Avoid placing comments inside <http-headers> as, in this release, it will prevent Icecast from parsing further <header> tags.

- -
- -
-

Relaying Streams

- -

This section contains the servers relay settings. The relays are implemented using a pull system where the receiving -server connects as if it’s a listener to the sending server.
-There are two types of relay setups:
-a “Master server relay” or a “Specific Mountpoint relay.”

- -

Master Relay

- -

A Master server relay is only supported between Icecast servers and is used to relay a number of -mountpoints from a remote Icecast server.

- -
<master-server>127.0.0.1</master-server>
-<master-server-port>8001</master-server-port>
-<master-update-interval>120</master-update-interval>
-<master-username>relay</master-username>
-<master-password>hackme</master-password>
-<relays-on-demand>0</relays-on-demand>
- -

The following diagram shows the basics of using a Master relay.
-Please note that the slave is configured with the <master-server>, <master-server-port>, etc… settings -and the master is the Icecast server from which the slave will pull mountpoints and relay them. Using a -Master server relay, all non-hidden mountpoints on the master can be -relayed using this mechanism.

- -

Master-Slave server diagram

- -

A server is configured as a Master Server relay by specifying the <master-server>, <master-server-port>, -<master-update-interval>, <master-password> values in the config file. The server that is being relayed -does not need any special configuration.

- -
-
master-server
-
This is the IP for the server which contains the mountpoints to be relayed (Master Server).
-
master-server-port
-
This is the TCP Port for the server which contains the mountpoints to be relayed (Master Server).
-
master-update-interval
-
The interval (in seconds) that the Relay Server will poll the Master Server for any new mountpoints to relay.
-
master-username
-
This is the relay username on the master server. It is used to query the server for a list of mountpoints to -relay. If not specified then relay is used.
-
master-password
-
This is the relay password on the Master server. It is used to query the server for a list of mountpoints to -relay.
-
relays-on-demand
-
Global on-demand setting for relays. Because you do not have individual relay options when using a master server -relay, you still may want those relays to only pull the stream when there is at least one listener on the slave. -The typical case here is to avoid surplus bandwidth costs when no one is listening.
-
- -

Specific Mountpoint Relay

- -

If only specific mountpoints need to be relayed, then you can configure Icecast with a “Specific Mountpoint Relay”.

- -

The following diagram shows the basics of using a Specific Mountpoint relay. Note that the relaying Icecast is -configured with the <relay> settings and will pull the specified mountpoint(s) and relay them to the listeners. -Using a Specific Mountpoint Relay, only those mountpoints specified will be relayed.

- -

Relay server diagram

- -

Specific Mountpoint Relays can be configured to relay from an Icecast 2 server, as well as Icecast 1.x and Shoutcast. -A server is configured as a Specific Mountpoint Server relay by specifying a <relay> XML chunk in the config file -for each mountpoint to be relayed. The server that is being relayed does not need any special configuration.

- -
<relay>
-    <server>127.0.0.1</server>
-    <port>8001</port>
-    <mount>/example.ogg</mount>
-    <local-mount>/different.ogg</local-mount>
-    <username>joe</username>
-    <password>soap</password>
-    <relay-shoutcast-metadata>0</relay-shoutcast-metadata>
-    <on-demand>1</on-demand>
-</relay>
- -
-
server
-
This is the IP for the server which contains the mountpoint to be relayed.
-
port
-
This is the TCP Port for the server which contains the mountpoint to be relayed.
-
mount
-
The mountpoint located on the remote server. If you are relaying a shoutcast stream, -this should be a / or /name.
-
local-mount
-
The name to use for the local mountpoint. This is what the mount will be named on the relaying server. -By default the remote mountpoint name is used.
-
username
-
The source of the relay may require authentication itself, if so state the username here.
-
password
-
The source of the relay may require authentication itself, if so state the password here.
-
relay-shoutcast-metadata
-
If you are relaying a Shoutcast stream, you may want to specify this indicator to also relay the metadata -(song titles) that are part of the Shoutcast data stream. By default this is enabled -but it is up to the remote server on whether it sends any.
-1: enabled, 0: disabled
-
on-demand
-
An on-demand relay will only retrieve the stream if there are listeners requesting the stream. -1: enabled, 0: disabled (default is <relays-on-demand>). This is useful in cases where you want to -limit bandwidth costs when no one is listening.
-
- -
- -
-

Mount Specific Settings

- - - -
<mount type="normal">
-    <mount-name>/example-complex.ogg</mount-name>
-    <username>othersource</username>
-    <password>hackmemore</password>
-    <max-listeners>1</max-listeners>
-    <max-listener-duration>3600</max-listener-duration>
-    <dump-file>/tmp/dump-example1.ogg</dump-file>
-    <intro>/intro.ogg</intro>
-    <fallback-mount>/example2.ogg</fallback-mount>
-    <fallback-override>1</fallback-override>
-    <fallback-when-full>1</fallback-when-full>
-    <charset>ISO8859-1</charset>
-    <public>1</public>
-    <stream-name>My audio stream</stream-name>
-    <stream-description>My audio description</stream-description>
-    <stream-url>http://some.place.com</stream-url>
-    <genre>classical</genre>
-    <bitrate>64</bitrate>
-    <type>application/ogg</type>
-    <subtype>vorbis</subtype>
-    <hidden>1</hidden>
-    <burst-size>65536</burst-size>
-    <mp3-metadata-interval>4096</mp3-metadata-interval>
-    <authentication type="xxxxxx">
-            <!-- See authentication documentation -->
-    </authentication>
-    <http-headers>
-            <header name="Access-Control-Allow-Origin" value="*" />
-            <header name="X-Robots-Tag" value="index, noarchive" />
-            <header name="foo" value="bar" status="200" />
-            <header name="Nelson" value="Ha-Ha!" status="404" />
-    </http-headers>
-    <on-connect>/home/icecast/bin/source-start</on-connect>
-    <on-disconnect>/home/icecast/bin/source-end</on-disconnect>
-</mount>
- -

This section contains the settings which apply only to a specific mountpoint and applies to an incoming -stream whether it is a relay or a source client. The purpose of the mount definition is to state certain -information that can override either global/default settings or settings provided from the incoming stream.

- -

A mount does not need to be stated for each incoming source although you may want to specific certain settings -like the maximum number of listeners or a mountpoint specific username/password. As a general rule, only define -what you need to but each mount definition needs at least the mount-name. Changes to most of these will apply -across a configuration file re-read even on active streams, however some only apply when the stream starts or -ends.

- -
-
type
-
The type of the mount point (default: “normal”). A mount of type “default” -can be used to specify common values for multiple mountpoints.
-Note that default mountpoints won’t merge with other mount blocks. -You only get those values if no type="normal" mount block exists -corresponding to your mountpoint.
-
mount-name
-
The name of the mount point for which these settings apply. -MUST NOT be used in case of mount type “default”.
-
- - -
-
username
-
An optional value which will set the username that a source must use to connect using this mountpoint. -Do not set this value unless you are sure that the source clients connecting to the mount point can be -configured to send a username other than source.
-If this value is not present the default username is source.
-
- - -
-
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.
-
max-listeners
-
An optional value which will set the maximum number of listeners that can be attached to this mountpoint.
-
max-listener-duration
-
An optional value which will set the length of time a listener will stay connected to the stream.
-An auth component may override this.
-
dump-file
-
An optional value which will set the filename which will be a dump of the stream coming through -on this mountpoint. This filename is processed with strftime(3). This allows to use variables like %F.
-
intro
-
An optional value which will specify the file those contents will be sent to new listeners when they -connect but before the normal stream is sent. Make sure the format of the file specified matches the -streaming format. The specified file is appended to webroot before being opened.
-
fallback-mount
-
This optional value specifies a mountpoint that clients are automatically moved -to if the source shuts down or is not streaming at the time a listener connects. Only one can be -listed in each mount and should refer to another mountpoint on the same server that is streaming in -the same streaming format.
-If clients cannot fallback to another mountpoint, due to a missing -fallback-mount or it states a mountpoint that is just not available, then those clients will be -disconnected. If clients are falling back to a mountpoint and the fallback-mount is not actively -streaming but defines a fallback-mount itself then those clients may be moved there instead. This -multi-level fallback allows clients to cascade several mountpoints.
-A fallback mount can also state a file that is located in webroot. This is useful for playing a -pre-recorded file in the case of a stream going down. It will repeat until either the listener -disconnects or a stream comes back available and takes the listeners back. As per usual, the file -format should match the stream format, failing to do so may cause problems with playback.
-Note that the fallback file is not timed so be careful if you intend to relay this. They are fine -on slave streams but don’t use them on master streams, if you do then the relay will consume stream -data at a faster rate and the listeners on the relay would eventually get kicked off.
-
fallback-override
-
When enabled, this allows a connecting source client or relay on this mountpoint to move listening -clients back from the fallback mount.
-
fallback-when-full
-
When set to 1, this will cause new listeners, when the max listener count for the mountpoint has -been reached, to move to the fallback mount if there is one specified.
-
no-yp (deprecated)
-
Setting this option prevents this mountpoint from advertising on YP. The default is 0 so YP advertising -can occur however you may want to prevent it here if you intend listeners to connect to a local relay instead.
-Deprecated option, replaced by <public>
-
charset
-
For non-Ogg streams like MP3, the metadata that is inserted into the stream often has no defined character set. -We have traditionally assumed UTF8 as it allows for multiple language sets on the web pages and stream directory, -however many source clients for MP3 type streams have assumed Latin1 (ISO 8859-1) or leave it to whatever character -set is in use on the source client system.
-This character mismatch has been known to cause a problem as the stats engine and stream directory servers want UTF8 -so now we assume Latin1 for non-Ogg streams (to handle the common case) but you can specify an alternative character -set with this option.
-The source clients can also specify a charset= parameter to the metadata update URL if they so wish.
-
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 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.
-
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.
-
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.
-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.
-
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.
-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.
-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
-
burst-size
-
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
-
This optional setting specifies what interval, in bytes, there is between metadata updates within shoutcast compatible streams. -This only applies to new listeners connecting on this mountpoint, not existing listeners falling back to this mountpoint. The -default is either the hardcoded server default or the value passed from a relay.
-
hidden
-
Enable this to prevent this mount from being shown on the xsl pages. This is mainly for cases where a local relay is configured -and you do not want the source of the local 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 authentication and URL based source authentication here.
-
http-headers
-
This element is placed anywhere inside the mount section of the icecast config. It will contain <header> child elements, that specify the actual HTTP headers one by one.
-
header
-
This tag specifies the actual header to be sent to a HTTP client in response to every request for this mount point, but currently only if the HTTP status code is “200”. -This tag can contain the following attributes: - -
    -
  • name is required and its value specifies the HTTP header field name.
  • -
  • value is required and its value specifies the HTTP header field value.
  • -
-
-
on-connect
-
State a program that is run when the source is started. It is passed a parameter which is the name of the mountpoint that is starting. -The processing of the stream does not wait for the script to end. -Caution should be exercised as there is a small chance of stream file descriptors being mixed up with script file descriptors, if the FD numbers go above 1024. This will be further addressed in the next Icecast release. -This option is not available on Win32
-
on-disconnect
-
State a program that is run when the source ends. It is passed a parameter which is the name of the mountpoint that has ended. -The processing of the stream does not wait for the script to end.
-Caution should be exercised as there is a small chance of stream file descriptors being mixed up with script file descriptors, if the FD numbers go above 1024. This will be further addressed in the next Icecast release. -This option is not available on Win32
-
- -
- -
-

Path Settings

- -
<paths>
-    <basedir>./</basedir>
-    <logdir>./logs</logdir>
-    <pidfile>./icecast.pid</pidfile>
-    <webroot>./web</webroot>
-    <adminroot>./admin</adminroot>
-    <allow-ip>/path/to/ip_allowlist</allow-ip>
-    <deny-ip>/path_to_ip_denylist</deny-ip>
-    <ssl-certificate>/path/to/certificate.pem</ssl-certificate>
-    <ssl-allowed-ciphers>ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS</ssl-allowed-ciphers>
-    <alias source="/foo" dest="/bar"/>
-</paths>
- -

This section contains paths which are used for various things within icecast. All paths (other than any aliases) should not end in a /.

- -
-
basedir
-
This path is used in conjunction with the chroot settings, and specifies the base directory that is chrooted to when the server is started.
-This feature is not supported on Win32.
-
logdir
-
This path specifies the base directory used for logging. Both the error.log and access.log will be created relative to this directory.
-
pidfile
-
This pathname specifies the file to write at startup and to remove at normal shutdown. The file contains the process id of the icecast process.
-This could be read and used for sending signals to Icecast.
-
webroot
-
This path specifies the base directory used for all static file requests. This directory can contain all standard file types -(including mp3s and ogg vorbis files). For example, if webroot is set to /var/share/icecast2, and a request for -http://server:port/mp3/stuff.mp3 comes in, then the file /var/share/icecast2/mp3/stuff.mp3 will be served.
-
adminroot
-
This path specifies the base directory used for all admin requests. More specifically, this is used to hold the XSLT scripts used -for the web-based admin interface. The admin directory contained within the icecast distribution contains these files.
-
allow-ip
-
If specified, this points to the location of a file that contains a list of IP addresses that will be allowed to connect to Icecast. -This could be useful in cases where a master only feeds known slaves.
-The format of the file is simple, one IP per line.
-
deny-ip
-
If specified, this points to the location of a file that contains a list of IP addressess that will be dropped immediately. -This is mainly for problem clients when you have no access to any firewall configuration.
-The format of the file is simple, one IP per line.
-
- - -
-
alias
-
Aliases are used to provide a way to create multiple mountpoints that refer to the same mountpoint.
-For example: <alias source="/foo" dest="/bar">
-
ssl-certificate
-
If specified, this points to the location of a file that contains both the X.509 private and public key. -This is required for HTTPS support to be enabled. Please note that the user Icecast is running as must be able to read the file. Failing to ensure this will cause a “Invalid cert file” WARN message, just as if the file wasn’t there.
-
ssl-allowed-ciphers
-
This optional tag specifies the list of allowed ciphers passed on to the SSL library. -Icecast contains a set of defaults conforming to current best practices and you should only override those, using this tag, if you know exactly what you are doing.
-
- -
- -
-

Logging Settings

- -
<logging>
-    <accesslog>access.log</accesslog>
-    <errorlog>error.log</errorlog>
-    <playlistlog>playlist.log</playlistlog>
-    <loglevel>4</loglevel> <!-- 4 Debug, 3 Info, 2 Warn, 1 Error -->
-</logging>
- -

This section contains information relating to logging within Icecast. There are three logfiles currently generated by Icecast, -an error.log (where all log messages are placed), an access.log (where all stream/admin/http requests are logged) and an -optional playlist.log.

- -

Note that on non-win32 platforms, a HUP signal can be sent to Icecast in which the log files are re-opened for appending giving the ability move/remove the log files.

- -

If you set any of the filenames to a simple dash (e.g. <accesslog>-</accesslog>) then Icecast will direct the log output to -STDERR instead of a file.

- -
-
accesslog
-
Into this file, all requests made to the icecast2 will be logged. This file is relative to the path specified by the <logdir> config value.
-
errorlog
-
All Icecast generated log messages will be written to this file. If the loglevel is set too high (Debug for instance) then -this file can grow fairly large over time. Currently, there is no log-rotation implemented.
-
playlistlog
-
Into this file, a log of all metadata for each mountpoint will be written. The format of the logfile will most likely change over time -as we narrow in on a standard format for this. Currently, the file is pipe delimited. This is optional and can be removed entirely -from the config file.
-
logsize
-
This value specifies (in Kbytes) the maxmimum size of any of the log files. When the logfile grows beyond this value, icecast will either -rename it to logfile.old, or add a timestamp to the archived file (if logarchive is enabled).
-
logarchive
-
If this value is set, then Icecast will append a timestamp to the end of the logfile name when logsize has been reached. If disabled, then -the default behavior is to rename the logfile to logfile.old (overwriting any previously saved logfiles). We disable this by default to -prevent the filling up of filesystems for people who don’t care (or know) that their logs are growing.
-
loglevel
-
Indicates what messages are logged by icecast. Log messages are categorized into one of 4 types, Debug, Info, Warn, and Error.
- -

The following mapping can be used to set the appropriate value:

- -
    -
  • loglevel = 4: Debug, Info, Warn, Error messages are printed
  • -
  • loglevel = 3: Info, Warn, Error messages are printed
  • -
  • loglevel = 2: Warn, Error messages are printed
  • -
  • loglevel = 1: Error messages only are printed
  • -
-
-
- -
- -
-

Security Settings

- -
<security>
-    <chroot>0</chroot>
-    <changeowner>
-        <user>nobody</user>
-        <group>nogroup</group>
-    </changeowner>
-</security>
- -

This section contains configuration settings that can be used to secure the icecast server by performing a chroot to a secured location or changing user and group on start-up. The latter allows icecast to bind to priviledged ports like 80 and 443, by being started as root and then dropping to the configured user/group after binding listener-sockets. -This is currently not supported on Win32.

- -
-
chroot
-
An indicator which specifies whether a chroot() will be done when the server is started. -The chrooted path is specified by the <basedir> configuration value. -Setting up and using a chroot is an advanced concept and not in the scope of this document.
-
changeowner
-
This section indicates the user and group that will own the icecast process when it is started.
-These need to be valid users on the system. Icecast must be started as root for this to work.
-
- -
- -
- - - - - diff --git a/doc/docs/admin_interface.md b/doc/docs/admin_interface.md new file mode 100644 index 0000000000000000000000000000000000000000..6d115ca80c59302ba99e0d6c8abed8d9e643a9e0 --- /dev/null +++ b/doc/docs/admin_interface.md @@ -0,0 +1,97 @@ +This section contains information about the admin interface of Icecast. Through this interface the user can manipulate many server features. From it you can gather statistics, move listeners from one mountpoint to another, disconnect connected sources or listeners and many other activities. Each function is enumerated here as well as an example usage of the function. + +Each of these functions requires HTTP authentication via the appropriate username and password. For mount-specific functions, you may use either the `` and `` specified in the Icecast config file, or the username and password specified for that mountpoint (if any). For general functions (not specific to a single mountpoint), you must use the admin username and password. + +# Admin Functions (mount specific) +All these admin functions are mount specific in that they only apply to a particular mountpoint +(as opposed to applying to the entire server). Each of these functions requires a mountpoint to +be specified as input. + +## Metadata Update +This function provides the ability for either a source client or any external program to update +the metadata information for a particular mountpoint. + +Example: +`/admin/metadata?mount=/stream&mode=updinfo&song=ACDC+Back+In+Black` + +## Fallback Update +This function provides the ability for either a source client or any external program to update the +“fallback mountpoint” for a particular mountpoint. Fallback mounts are those that are used in the even +of a source client disconnection. If a source client disconnects for some reason that all currently +connected clients are sent immediately to the fallback mountpoint. + +Example: +`/admin/fallbacks?mount=/stream.ogg&fallback=/fallback.ogg` + +## List Clients +This function lists all the clients currently connected to a specific mountpoint. The results are sent +back in XML form. + +Example: +`/admin/listclients?mount=/stream.ogg` + +## Move Clients (Listeners) +This function provides the ability to migrate currently connected listeners from one mountpoint to another. +This function requires 2 mountpoints to be passed in: mount (the *from* mountpoint) and destination +(the _to_ mountpoint). After processing this function all currently connected listeners on mount will +be connected to destination. Note that the destination mountpoint must exist and have a sounce client +already feeding it a stream. + +Example: +`/admin/moveclients?mount=/stream.ogg&destination=/newstream.ogg` + +## Kill Client (Listener) +This function provides the ability to disconnect a specific listener of a currently connected mountpoint. +Listeners are identified by a unique id that can be retrieved by via the “List Clients” admin function. +This id must be passed in to the request via the variable `id`. After processing this request, the listener will no longer be +connected to the mountpoint. + +Example: +`/admin/killclient?mount=/mystream.ogg&id=21` + +## Kill Source +This function will provide the ability to disconnect a specific mountpoint from the server. The mountpoint +to be disconnected is specified via the variable `mount`. + +Example: +`/admin/killsource?mount=/mystream.ogg` + + +# Admin Functions (general) + +## Stats +The stats function provides the ability to query the internal statistics kept by the Icecast server. +Almost all information about the internal workings of the server such as the mountpoints connected, +how many client requests have been served, how many listeners for each mountpoint, etc. are available +via this admin function. + +Example: +`/admin/stats` + +## List Mounts +The list mounts function provides the ability to view all the currently connected mountpoints. + +Example: +`/admin/listmounts` + +# Web-Based Admin Interface +As an alternative to manually invoking these URLs, there is a web-based admin interface. +This interface provides the same functions that were identified and described above but presents them in +a nicer way. The web-based admin Interface to Icecast is shipped with Icecast provided in the +`admin` directory and comes ready to use. + +The main path for the Web-Based Admin Interface is: +`/admin/stats.xsl` + +## Advanced + +The web-based admin interface is a series of XSL-Transform files which are used to display all the XML obtained +via the URL admin interface. This can be changed and modified to suit the user's need. Knowledge of +XSLT and transformations from XML to HTML are required in order to make changes to these scripts. + +__Modification of existing XSLT transforms in `/admin` is allowed, but new files cannot be created here.__ + +Creation of new XSLT transforms as well as modification of existing transforms is allowed in the `/web` directory. +These work using the document returned by the `/admin/stats` endpoint. +To see the XML document that is applied to each admin XSLT, just remove the .xsl in your request +(i.e. `/admin/listclients`). You can then code your XSL transform accordingly. \ No newline at end of file diff --git a/doc/docs/auth.md b/doc/docs/auth.md new file mode 100644 index 0000000000000000000000000000000000000000..679fa9d6d7e506b6ab25d1898d2cd652c46abdd1 --- /dev/null +++ b/doc/docs/auth.md @@ -0,0 +1,359 @@ +# Listener Authentication +Listener authentication is a feature of Icecast which allows you to secure a certain mountpoint such that in order to listen, +a listener must pass some verification test. With this feature, a simple pay-for-play operation (eg. user/pass), or some filtering +based on the listener connection can be performed. This section will show you the basics of setting up and maintaining this component. + +To define listener authentication, a group of tags are specified in the `` group relating to the mountpoint. This means +that authentication can apply to listeners of source clients or relays. + +The following authentication mechanisms can apply to listeners: + + +* htpasswd: lookup a named file for a matching username and password +* URL: issue web requests (eg. PHP) to match authentication + +The listener authentication within a specified mount in the icecast XML configuration can apply to either to a stream from a +source client, relay or a webroot based file. They do apply to intro files or fallback streams. + + +# htpasswd Listener Authentication +In order to use listener authentication, you __must__ configure a mount specific option. This means that you have to provide +a `` section in the main icecast config file. The following is an example: + + +```xml + + /example.ogg + + + +``` + +To support listener authentication you __must__ provide at a minimum `` and ``. +The `mount-name` is the name of the mountpoint that you will use to connect your source client with and `authentication` configures +what type of Icecast authenticator to use. +Currently, only `htpasswd` and `url` are implemented. Each authenticator has a variable number of options that are required and +these are specified as shown in the example. +The htpasswd authenticator requires a few parameters: +The first, `filename`, specifies the name of the file to use to store users and passwords. Note that this file need not exist +(and probably will not exist when you first set it up). +Icecast has built-in support for managing users and passwords via the web admin interface. More on this later in this section. +The second option, `allow_duplicate_users`, if set to `0`, will prevent multiple connections using the same username. Setting this +value to `1` will enable mutltiple connections from the same username on a given mountpoint. +Note there is no way to specify a “max connections” for a particular user. + +Icecast supports a mixture of streams that require listener authentication and those that do not. + +## Configuring Users and Passwords +Once the appropriate entries are made to the config file, connect your source client (using the mountpoint you named in +the config file). To configure users and passwords for this stream you must use the web-based admin interface. Navigate to +`http://server:ip/admin/stats.xsl` to begin. If you have configured everything properly, you should see a screen like the +following: + +![Screenshot of Admin Stats](img/listener_auth1.png) + +You will see a lock in front of all mountpoint configured for listener authentication. Also note that this page will +only show _connected_ mountpoints. + +To manage users and passwords for this mountpoint, click on the “Manage Authentication” link. The following screen will be shown: + +![Screenshot of Manage Authentication](img/listener_auth2.png) + +This screen will show all the users configured for this mountpoint. Adding users is as simple as entering a username and password +in the fields and clicking “Add”. +Note that usernames __must__ be unique and there are __no__ restrictions on passwords. You can delete users by clicking the appropriate +delete link next to each user. + +## Finishing it all off +Ok, so you've created your users, and you have everything setup properly, how do your users login? Well, we've provided a simple login +form that you can use for this purpose. This page (`http://server:port/auth.xsl`) will bring up a form that users can use to enter their +username and password. + +![Screenshot of Auth Page](img/listener_auth3.png) + +This page will serve a m3u with the username and password and in most cases should open the correct media player and begin playing +your stream. + +# URL + +Authenticating listeners via the URL method involves Icecast, when a listener connects, issuing requests to a web server +and checking the response headers. If a certain header is sent back then the listener connecting is allowed to continue, +if not, an error is sent back to the listener. + +The URLs specified will invoke some web server scripts like PHP to do any work that they may choose to do. All that is +required of the scripting language is that POST information can be handled and response headers can be sent back. +libcurl is used for the requesting so https connections may be possible, but be aware of the extra overhead involved. + +The useragent sent in each curl request will represent the Icecast server version. The response headers will depend on +whether the listener is to be accepted. In the case of rejection, a response header +`Icecast-Auth-Message: Reason` +should also be returned for placing in the log files. + +In order to use URL based listener authentication, you __must__ configure a mount specific option. This means that you +have to provide a `` section in the main Icecast config file. The following shows the list of options available: + + +```xml + + /example.ogg + + + +``` + +The options are described below in more detail, each of which is optional, but in each case, within the POST data, +the value for each setting is encoded. + + + +## mount_add + +This URL is for informing the auth server of a stream starting. No listener information is passed for this, +but it can be used to initialise any details the auth server may have. + +### POST Details +action +: `mount_add` + +mount +: the mountpoint starting up + +server +: the server name (``) + +port +: the server port + +### Example +`action=mount_add&mount=/live&server=icecast.example.org&port=8000` + + +## mount_remove +This URL is for informing the auth server of a stream finishing, like the start option, no listener details +are passed. + +### POST Details +action +: `mount_remove` + +mount +: the mountpoint being removed + +server +: the server name (``) + +port +: the server port + +### Example +`action=mount_remove&mount=/live&server=icecast.example.org&port=8000` + + +## listener_add +This is most likely to be used if anything. When a listener connects, before anything is sent back to them, this +request is processed. The default action is to reject a listener unless the auth server sends back a response header +which may be stated in the `header` option. + +### POST Details +action +: `listener_add` + +mount +: the mountpoint, including query parameters + +server +: the server name (``) + +port +: the server port + +user +: user as stated in listener HTTP basic auth + _May be blank_ + +pass +: pass as stated in listener HTTP basic auth + _May be blank_ + +client +: unique ID for the client within Icecast + +ip +: listeners IP address + +agent +: useragent from the listeners player + +__Note:__ The mount here (unlike the start/end options) states the requested url including any query parameters, +so for instance the requested URL can be `/stream.ogg&session=xyz`, but note that each option data is +escaped before being passed via POST. + +### Example +`action=listener_add&server=icecast.example.org&port=8000&client=1&mount=/live&user=&pass=&ip=127.0.0.1&agent=My%20player` + + +## listener_remove +This URL is for when a listener connection closes. + +### POST Details +action +: `listener_remove` + +mount +: the mountpoint + +server +: the server name (``) + +port +: the server port + +user +: user as stated in listener HTTP basic auth + _May be blank_ + +pass +: pass as stated in listener HTTP basic auth + _May be blank_ + +client +: unique ID for the client within Icecast + +ip +: listeners IP address + +agent +: useragent from the listeners player + +duration +: number of seconds the listener was connected for + +### Example +`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` + + +## stream_auth +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. + +### POST Details +action +: `stream_auth` + +mount +: the mountpoint + +server +: hostname of the Icecast server the client tries to connect to + +port +: the port of said server + +user +: username as sent by the source client + +pass +: password as sent by the source client + +admin +: admin request (read below) + +__Note:__ As admin requests can come in for a stream (eg. metadata update) these requests can be issued while +stream is active. For these `admin` is set to `1` in POST details. + +### Example +`action=stream_auth&mount=/stream.ogg&ip=192.0.2.0&server=icecast.example.org&port=8000&user=source&pass=password&admin=1` + + +## Other Options + +auth_header +: The expected response header to be returned that allows the authencation to take place may be specified here. + The default is: + `icecast-auth-user: 1` + but it could be anything you like, for instance: + `HTTP 200 OK` + +timelimit_header +: Listeners could have a time limit imposed on them, and if this header is sent back with a figure (which represents seconds) + then that is how long the client will remain connected for. + +headers +: 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 sent as POST parameters. + +header_prefix +: This is the prefix used for passing client headers. See headers for details. + +username +: The HTTP basic auth username used when `POST`ing to the auth endpoints. + +password +: The HTTP basic auth password used when `POST`ing to the auth endpoints. + + +# A note about players and authentication +We do not have an exaustive list of players that support listener authentication. +We use standard HTTP basic authentication, and in general, many media players support this if they support anything at all. +Winamp and Foobar2000 support HTTP basic authentication on Windows, and XMMS supports it on UNIX platforms. Winamp/XMMS at +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 `` group relating to the mountpoint. + +The following authentication mechanisms can apply to sources: + + +* BASIC: `` and possibly `` in the `` section +* URL: issue web requests (eg. PHP) to match authentication + +## URL authentication: `stream_auth` +A `` can contain a section `` and therein +`