aniani/icecast-server
1
0
Fork 0
mirror of https://gitlab.xiph.org/xiph/icecast-server.git synced 2024-06-16 06:15:24 +00:00
Code

Add mkdocs to repo and generate them with automake

Browse Source
This commit is contained in:
Marvin Scholz 2017-05-10 13:01:45 +02:00
parent b7087c38e0
commit d30d192bca
51 changed files with 1766 additions and 3419 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
configure.ac
View File

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

48
doc/Makefile.am
View File

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

143
doc/admin-interface.html
View File

@ -1,143 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Admin Interface</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Admin Interface</h2>
<div class="article">
<h3 id="overview">Overview</h3>
<p>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.</p>
<p>Each of these functions requires HTTP authentication via the appropriate username and password. For mount-specific functions, you may use either the <code>&lt;admin-username&gt;</code> and <code>&lt;admin-password&gt;</code> 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.</p>
</div>
<div class="article">
<h3 id="admin-functions-mount-specific">Admin Functions (mount specific)</h3>
<p>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.</p>
<h4 id="metadata-update">Metadata Update</h4>
<p>This function provides the ability for either a source client or any external program to update
the metadata information for a particular mountpoint.</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/metadata?mount=/mystream&amp;mode=updinfo&amp;song=ACDC+Back+In+Black</code></p>
<h4 id="fallback-update">Fallback Update</h4>
<p>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.</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/fallbacks?mount=/mystream.ogg&amp;fallback=/myfallback.ogg</code></p>
<h4 id="list-clients">List Clients</h4>
<p>This function lists all the clients currently connected to a specific mountpoint. The results are sent
back in XML form.</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/listclients?mount=/mystream.ogg</code></p>
<h4 id="move-clients-listeners">Move Clients (Listeners)</h4>
<p>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 <em>from</em> mountpoint) and destination
(the <em>to</em> 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.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/moveclients?mount=/mystream.ogg&amp;destination=/mynewstream.ogg</code></p>
<h4 id="kill-client-listener">Kill Client (Listener)</h4>
<p>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 <code>id</code>. After processing this request, the listener will no longer be
connected to the mountpoint.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/killclient?mount=/mystream.ogg&amp;id=21</code></p>
<h4 id="kill-source">Kill Source</h4>
<p>This function will provide the ability to disconnect a specific mountpoint from the server. The mountpoint
to be disconnected is specified via the variable <code>mount</code>.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/killsource?mount=/mystream.ogg</code></p>
</div>
<div class="article">
<h3 id="admin-functions-general">Admin Functions (general)</h3>
<h4 id="stats">Stats</h4>
<p>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.<br />
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!</p>
<p>Example:<br />
<code>http://192.168.1.10:8000/admin/stats</code></p>
<h4 id="list-mounts">List Mounts</h4>
<p>The list mounts function provides the ability to view all the currently connected mountpoints.</p>
<p>Example:
<code>http://192.168.1.10:8000/admin/listmounts</code></p>
</div>
<div class="article">
<h3 id="web-based-admin-interface">Web-Based Admin Interface</h3>
<p>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
<code>admin</code> 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 <code>&lt;adminroot&gt;</code> config variable.<br />
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. </p>
<p>The main URL for the Web-Based Admin Interface is:<br />
<code>http://192.168.1.10:8000/admin/stats.xsl</code> </p>
<p>From this URL all of the other admin functions can be exercised.
<strong>Modification of existing XSLT transforms in <code>/admin</code> is allowed, but new files cannot be created here</strong>.
Creation of new XSLT transforms as well as modification of existing transforms is allowed in <code>/web</code>.
These work using the document returned by <code>/admin/stats.xml</code>.<br />
To see the XML document that is applied to each admin XSLT, just remove the <code>.xsl</code> in your request
(i.e. <code>/admin/listclients</code>). You can then code your XSLT transform accordingly.</p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

5
doc/assets/Makefile.am
View File

@ -1,5 +0,0 @@
## Process this file with automake to produce Makefile.in
AUTOMAKE_OPTIONS = foreign
SUBDIRS = css font img

8
doc/assets/css/Makefile.am
View File

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

981
doc/assets/css/style.css
View File

@ -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%;}

BIN
doc/assets/font/FiraMono-Bold.eot
View File

Binary file not shown.

BIN
doc/assets/font/FiraMono-Bold.woff
View File

Binary file not shown.

BIN
doc/assets/font/FiraMono-Regular.eot
View File

Binary file not shown.

BIN
doc/assets/font/FiraMono-Regular.woff
View File

Binary file not shown.

BIN
doc/assets/font/FiraSans-Bold.eot
View File

Binary file not shown.

BIN
doc/assets/font/FiraSans-Bold.woff
View File

Binary file not shown.

BIN
doc/assets/font/FiraSans-BoldItalic.eot
View File

Binary file not shown.

BIN
doc/assets/font/FiraSans-BoldItalic.woff
View File

Binary file not shown.

BIN
doc/assets/font/FiraSans-Italic.eot
View File

Binary file not shown.

BIN
doc/assets/font/FiraSans-Italic.woff
View File

Binary file not shown.

BIN
doc/assets/font/FiraSans-Regular.eot
View File

Binary file not shown.

BIN
doc/assets/font/FiraSans-Regular.woff
View File

Binary file not shown.

13
doc/assets/font/Makefile.am
View File

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

8
doc/assets/img/Makefile.am
View File

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

21
doc/assets/img/xiph-community.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 59 KiB

359
doc/auth.html
View File

@ -1,359 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Authentication</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Authentication</h2>
<div class="article">
<h3 id="listener-authentication">Listener Authentication</h3>
<p>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. </p>
<p>To define listener authentication, a group of tags are specified in the <code>&lt;mount&gt;</code> group relating to the mountpoint. This means
that authentication can apply to listeners of source clients or relays. </p>
<p>The following authentication mechanisms can apply to listeners:</p>
<ul>
<li>htpasswd: lookup a named file for a matching username and password</li>
<li>URL: issue web requests (eg. PHP) to match authentication</li>
</ul>
<p>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.</p>
</div>
<div class="article">
<h3 id="htpasswd-listener-authentication">htpasswd Listener Authentication</h3>
<p>In order to use listener authentication, you <strong>must</strong> configure a mount specific option. This means that you have to provide
a <code>&lt;mount&gt;</code> section in the main icecast config file. The following is an example:</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;mount&gt;</span>
<span class="nt">&lt;mount-name&gt;</span>/example.ogg<span class="nt">&lt;/mount-name&gt;</span>
<span class="nt">&lt;authentication</span> <span class="na">type=</span><span class="s">&quot;htpasswd&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;filename&quot;</span> <span class="na">value=</span><span class="s">&quot;myauth&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;allow_duplicate_users&quot;</span> <span class="na">value=</span><span class="s">&quot;0&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/authentication&gt;</span>
<span class="nt">&lt;/mount&gt;</span></code></pre></div>
<p>To support listener authentication you <strong>must</strong> provide at a minimum <code>&lt;mount-name&gt;</code> and <code>&lt;authentication&gt;</code>.<br />
The <code>mount-name</code> is the name of the mountpoint that you will use to connect your source client with and <code>authentication</code> configures
what type of Icecast authenticator to use.<br />
Currently, only <code>htpasswd</code> and <code>url</code> are implemented. Each authenticator has a variable number of options that are required and
these are specified as shown in the example.<br />
The htpasswd authenticator requires a few parameters:<br />
The first, <code>filename</code>, 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).<br />
Icecast has built-in support for managing users and passwords via the web admin interface. More on this later in this section.<br />
The second option, <code>allow_duplicate_users</code>, if set to <code>0</code>, will prevent multiple connections using the same username. Setting this
value to <code>1</code> will enable mutltiple connections from the same username on a given mountpoint.<br />
Note there is no way to specify a “max connections” for a particular user. </p>
<p>Icecast supports a mixture of streams that require listener authentication and those that do not.</p>
<h4 id="configuring-users-and-passwords">Configuring Users and Passwords</h4>
<p>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
<code>http://server:ip/admin/stats.xsl</code> to begin. If you have configured everything properly, you should see a screen like the
following:</p>
<p><img src="img/listener_auth1.png" alt="Screenshot of Admin Stats" /></p>
<p>You will see a lock in front of all mountpoint configured for listener authentication. Also note that this page will
only show <em>connected</em> mountpoints.</p>
<p>To manage users and passwords for this mountpoint, click on the “Manage Authentication” link. The following screen will be shown:</p>
<p><img src="img/listener_auth2.png" alt="Screenshot of Manage Authentication" /></p>
<p>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”.<br />
Note that usernames <strong>must</strong> be unique and there are <strong>no</strong> restrictions on passwords. You can delete users by clicking the appropriate
delete link next to each user.</p>
<h4 id="finishing-it-all-off">Finishing it all off</h4>
<p>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 (<code>http://server:port/auth.xsl</code>) will bring up a form that users can use to enter their
username and password.</p>
<p><img src="img/listener_auth3.png" alt="Screenshot of Auth Page" /></p>
<p>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.</p>
</div>
<div class="article">
<h3 id="url">URL</h3>
<p>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. </p>
<p>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.<br />
libcurl is used for the requesting so https connections may be possible, but be aware of the extra overhead involved. </p>
<p>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<br />
<code>Icecast-Auth-Message: Reason</code><br />
should also be returned for placing in the log files. </p>
<p>In order to use URL based listener authentication, you <strong>must</strong> configure a mount specific option. This means that you
have to provide a <code>&lt;mount&gt;</code> section in the main Icecast config file. The following shows the list of options available: </p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;mount&gt;</span>
<span class="nt">&lt;mount-name&gt;</span>/example.ogg<span class="nt">&lt;/mount-name&gt;</span>
<span class="nt">&lt;authentication</span> <span class="na">type=</span><span class="s">&quot;url&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;mount_add&quot;</span> <span class="na">value=</span><span class="s">&quot;http://auth.example.org/stream_start.php&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;mount_remove&quot;</span> <span class="na">value=</span><span class="s">&quot;http://auth.example.org/stream_end.php&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;listener_add&quot;</span> <span class="na">value=</span><span class="s">&quot;http://auth.example.org/listener_joined.php&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;listener_remove&quot;</span> <span class="na">value=</span><span class="s">&quot;http://auth.example.org/listener_left.php&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;username&quot;</span> <span class="na">value=</span><span class="s">&quot;user&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;password&quot;</span> <span class="na">value=</span><span class="s">&quot;pass&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;auth_header&quot;</span> <span class="na">value=</span><span class="s">&quot;icecast-auth-user: 1&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;timelimit_header&quot;</span> <span class="na">value=</span><span class="s">&quot;icecast-auth-timelimit:&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;headers&quot;</span> <span class="na">value=</span><span class="s">&quot;x-pragma,x-token&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;header_prefix&quot;</span> <span class="na">value=</span><span class="s">&quot;ClientHeader.&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;option</span> <span class="na">name=</span><span class="s">&quot;stream_auth&quot;</span> <span class="na">value=</span><span class="s">&quot;http://auth.example.org/source.php&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/authentication&gt;</span>
<span class="nt">&lt;/mount&gt;</span></code></pre></div>
<p>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.</p>
<h4 id="mountadd">mount_add</h4>
<p>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. </p>
<h5 id="post-details">POST Details</h5>
<dl>
<dt>action</dt>
<dd><code>mount_add</code></dd>
<dt>mount</dt>
<dd>the mountpoint starting up</dd>
<dt>server</dt>
<dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
<dt>port</dt>
<dd>the server port</dd>
</dl>
<h5 id="example">Example</h5>
<p><code>action=mount_add&amp;mount=/live&amp;server=icecast.example.org&amp;port=8000</code></p>
<h4 id="mountremove">mount_remove</h4>
<p>This URL is for informing the auth server of a stream finishing, like the start option, no listener details
are passed. </p>
<h5 id="post-details-1">POST Details</h5>
<dl>
<dt>action</dt>
<dd><code>mount_remove</code></dd>
<dt>mount</dt>
<dd>the mountpoint being removed</dd>
<dt>server</dt>
<dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
<dt>port</dt>
<dd>the server port</dd>
</dl>
<h5 id="example-1">Example</h5>
<p><code>action=mount_remove&amp;mount=/live&amp;server=icecast.example.org&amp;port=8000</code></p>
<h4 id="listeneradd">listener_add</h4>
<p>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 <code>header</code> option.</p>
<h5 id="post-details-2">POST Details</h5>
<dl>
<dt>action</dt>
<dd><code>listener_add</code></dd>
<dt>mount</dt>
<dd>the mountpoint, including query parameters</dd>
<dt>server</dt>
<dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
<dt>port</dt>
<dd>the server port</dd>
<dt>user</dt>
<dd>user as stated in listener HTTP basic auth<br />
<em>May be blank</em></dd>
<dt>pass</dt>
<dd>pass as stated in listener HTTP basic auth
<em>May be blank</em></dd>
<dt>client</dt>
<dd>unique ID for the client within Icecast</dd>
<dt>ip</dt>
<dd>listeners IP address</dd>
<dt>agent</dt>
<dd>useragent from the listeners player</dd>
</dl>
<p><strong>Note:</strong> The mount here (unlike the start/end options) states the requested url including any query parameters,
so for instance the requested URL can be <code>/stream.ogg&amp;session=xyz</code>, but note that each option data is
escaped before being passed via POST.</p>
<h5 id="example-2">Example</h5>
<p><code>action=listener_add&amp;server=icecast.example.org&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;ip=127.0.0.1&amp;agent=My%20player</code> </p>
<h4 id="listenerremove">listener_remove</h4>
<p>This URL is for when a listener connection closes.</p>
<h5 id="post-details-3">POST Details</h5>
<dl>
<dt>action</dt>
<dd><code>listener_remove</code></dd>
<dt>mount</dt>
<dd>the mountpoint</dd>
<dt>server</dt>
<dd>the server name (<code>&lt;hostname&gt;</code>)</dd>
<dt>port</dt>
<dd>the server port</dd>
<dt>user</dt>
<dd>user as stated in listener HTTP basic auth<br />
<em>May be blank</em></dd>
<dt>pass</dt>
<dd>pass as stated in listener HTTP basic auth
<em>May be blank</em></dd>
<dt>client</dt>
<dd>unique ID for the client within Icecast</dd>
<dt>ip</dt>
<dd>listeners IP address</dd>
<dt>agent</dt>
<dd>useragent from the listeners player</dd>
<dt>duration</dt>
<dd>number of seconds the listener was connected for</dd>
</dl>
<h5 id="example-3">Example</h5>
<p><code>action=listener_remove&amp;server=icecast.example.org&amp;port=8000&amp;client=1&amp;mount=/live&amp;user=&amp;pass=&amp;duration=3600&amp;ip=127.0.0.1&amp;agent=My%20player</code></p>
<h4 id="streamauth">stream_auth</h4>
<p>Technically this does not belong to listener authentication, but due to its similarity it is explained here too.<br />
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 <code>header</code> option.</p>
<h5 id="post-details-4">POST Details</h5>
<dl>
<dt>action</dt>
<dd><code>stream_auth</code></dd>
<dt>mount</dt>
<dd>the mountpoint</dd>
<dt>server</dt>
<dd>hostname of the Icecast server the client tries to connect to</dd>
<dt>port</dt>
<dd>the port of said server</dd>
<dt>user</dt>
<dd>username as sent by the source client</dd>
<dt>pass</dt>
<dd>password as sent by the source client</dd>
<dt>admin</dt>
<dd>admin request (read below)</dd>
</dl>
<p><strong>Note:</strong> As admin requests can come in for a stream (eg. metadata update) these requests can be issued while
stream is active. For these <code>admin</code> is set to <code>1</code> in POST details.</p>
<h5 id="example-4">Example</h5>
<p><code>action=stream_auth&amp;mount=/stream.ogg&amp;ip=192.0.2.0&amp;server=icecast.example.org&amp;port=8000&amp;user=source&amp;pass=password&amp;admin=1</code></p>
<h4 id="other-options">Other Options</h4>
<dl>
<dt>auth_header</dt>
<dd>The expected response header to be returned that allows the authencation to take place may be specified here.<br />
The default is:<br />
<code>icecast-auth-user: 1</code><br />
but it could be anything you like, for instance:<br />
<code>HTTP 200 OK</code></dd>
<dt>timelimit_header</dt>
<dd>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.</dd>
<dt>headers</dt>
<dd>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.</dd>
<dt>header_prefix</dt>
<dd>This is the prefix used for passing client headers. See headers for details.</dd>
</dl>
</div>
<div class="article">
<h3 id="note-player-auth">A note about players and authentication</h3>
<p>We do not have an exaustive list of players that support listener authentication.<br />
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.</p>
</div>
<div class="article">
<h3 id="source-auth">Source Authentication</h3>
<p>Source authentication is a feature of Icecast which allows you to secure a certain mountpoint such that in order to stream to it,
a source client must pass some verification test. This section will show you the basics of setting up and maintaining this component.<br />
To define source authentication, a group of tags are specified in the <code>&lt;mount&gt;</code> group relating to the mountpoint. </p>
<p>The following authentication mechanisms can apply to sources:</p>
<ul>
<li>BASIC: <code>&lt;password&gt;</code> and possibly <code>&lt;username&gt;</code> in the <code>&lt;mount&gt;</code> section</li>
<li>URL: issue web requests (eg. PHP) to match authentication</li>
</ul>
<h4 id="url-authentication-streamauth">URL authentication: <code>stream_auth</code></h4>
<p>A <code>&lt;mount&gt;</code> can contain a section <code>&lt;authentication type="url"&gt;</code> and therein
<code>&lt;option name="stream_auth" value="http://auth.example.org/source.php"/&gt;</code>. 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 <code>header</code> option (same as listener auth). </p>
<h5 id="post-details-5">POST Details</h5>
<dl>
<dt>action</dt>
<dd><code>stream_auth</code></dd>
<dt>mount</dt>
<dd>the mountpoint</dd>
<dt>server</dt>
<dd>hostname of the Icecast server the client tries to connect to</dd>
<dt>port</dt>
<dd>the port of said server</dd>
<dt>user</dt>
<dd>username as sent by the source client</dd>
<dt>pass</dt>
<dd>password as sent by the source client</dd>
<dt>admin</dt>
<dd>admin request (read below)</dd>
</dl>
<p><strong>Note:</strong> As admin requests can come in for a stream (eg. metadata update) these requests can be issued while
stream is active. For these <code>admin</code> is set to <code>1</code> in POST details.</p>
<h5 id="example-5">Example</h5>
<p><code>action=stream_auth&amp;mount=/stream.ogg&amp;ip=192.0.2.0&amp;server=icecast.example.org&amp;port=8000&amp;user=source&amp;pass=password&amp;admin=1</code></p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

91
doc/basic-setup.html
View File

@ -1,91 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Basic Setup</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Basic Setup</h2>
<div class="article">
<h3 id="basic-requirements">Basic Requirements</h3>
<p>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.</p>
<p>There are two major components involved: the streaming server (Icecast in this case) and the source client.<br />
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.</p>
<p>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.</p>
</div>
<div class="article">
<h3 id="the-basics">The Basics</h3>
<p>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.</p>
<p>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.</p>
<p>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</p>
<ul>
<li><code>conf</code><br />
Contains the Icecast configuration file (<code>icecast.xml</code>) which defines all the configuration parameters for the server. </li>
<li><code>admin</code><br />
Contains xslt files which are used by the Icecast server to provide a web-based front end to the administration capabilities of the server. </li>
<li><code>logs</code><br />
This is a blank directory which (if specified in the config file) will contain all the logs (there are 2) for Icecast. </li>
</ul>
<p>The next step is to edit the <code>icecast.xml</code> 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:</p>
<p><code>&lt;hostname&gt;</code> - DNS name or IP address used for stream directory listings.<br />
<code>&lt;source-password&gt;</code> - Will be used for the source client authentication.<br />
<code>&lt;admin-password&gt;</code> - Will be used for authenticating admin features of Icecast.<br />
<code>&lt;listen-socket&gt;</code> (both port and bind-address) </p>
<p>Once the configuration file is modified, you should be able to start the server with the following command</p>
<pre><code>icecast -c /path/to/icecast.xml
</code></pre>
<p>If no error messages are generated, then check the <code>error.log</code> file for the ‘server started’ message, it will look something like :</p>
<pre><code>[2003-10-31 13:04:49] INFO main/main.c Icecast 2.3.0 server started
</code></pre>
<p>You may notice slight variations to the line above, the time will no doubt be different, and on some platforms the <code>main.c</code> is just main, but the key thing here is that the server is started, logging is working and the version is shown. </p>
<p>You can also verify that it started by visiting the following URL: <code>http://yourip:port/admin/stats.xml</code>. You should be prompted for a username and password. Enter the username <code>admin</code> and the password you entered for <code>&lt;admin-password&gt;</code>. If all is well, you should see an small XML tree which represents Icecast statistics (more about that later). </p>
<p>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: </p>
<p>IP address and Port of the icecast server - both of these come from <code>&lt;listen-socket&gt;</code><br />
source password - from <code>&lt;source-password&gt;</code> </p>
<p>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 <code>.ogg</code> (i,e. <code>/mystream.ogg</code>). 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). </p>
<p>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. </p>
<p>Now that you have the source connnected, listening to the stream involves simply opening the appropriate following URL in a browser: <code>http://yourip:port/mounpoint-you-specified</code>. So, for instance, if you attached your source client to an icecast server located at <code>192.0.2.23:8000</code> with a mountpoint of <code>/mystream.ogg</code>, then you would open: <code>http://192.0.2.23:8000/mystream.ogg</code> or <code>http://192.0.2.23:8000/mystream.ogg.m3u</code>. Note that the URL with <code>.m3u</code> 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 (<code>http://192.0.2.23:8000/mystream.ogg</code> in this case)</p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

149
doc/changes.html
View File

@ -1,149 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Changes</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Changes</h2>
<div id="v2.4.99.1" class="article">
<h3 id="version-24991">Version 2.4.99.1</h3>
<!-- FIXME -->
<ul>
<li>Roles</li>
<li>Events</li>
<li>Stuff</li>
<li>Read ChangeLog for details</li>
</ul>
<div id="v2.4.1" class="article">
<h3 id="version-241">Version 2.4.1</h3>
<h4 id="fixes">Fixes</h4>
<ul>
<li>Fixed cross-corruption of file descriptors by on-connect/on-disconnect scripts, specifically STDIN, STDOUT and STDERRR vs TCP connections.
<ul>
<li>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.</li>
<li>The STDIN/OUT/ERR problem is fixed reliably, but other problems could occur if both the script and the server use FDs &gt;1024 at the same time</li>
<li>This is now reasonably safe, but care should be exercised nevertheless. </li>
</ul>
</li>
<li>Disabled SSLv3 and SSL compression explicitly to improve security</li>
<li>Updated the default ciphers to be more secure</li>
<li>Fixed JSON status API problems
<ul>
<li>Put the XSLT last item check into every filtered tag.</li>
<li>This way we shouldn’t run into problems of this type anymore.</li>
<li>Also it should be easier to customize the XSLT this way, if someone wants to filter differently.</li>
</ul>
</li>
<li>Fixed <code>&lt;auth&gt;</code> in <code>&lt;mount type="default"&gt;</code> to work properly.</li>
<li>Fixed listener connection duration logging in access.log. Regression was introduced for only some platforms by an earlier security fix.</li>
<li>Fixed time zone reporting in _iso8601 fields on Windows.</li>
<li>added warnings on empty and default values of <code>&lt;fileserve&gt;</code>, <code>&lt;hostname&gt;</code>, <code>&lt;location&gt;</code>, <code>&lt;admin&gt;</code> and <code>&lt;server-id&gt;</code></li>
<li>send errorlog (loglevel WARN) to stderr prior to opening logfiles.</li>
<li>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.</li>
<li>Be more verbose in case of fileserve off. People disable fileserve and then wonder why the web interface CSS breaks.</li>
<li>More details in log messages
<ul>
<li>Add source IP adress to startup and source exit logging</li>
<li>Add mountpoint to some log lines</li>
</ul>
</li>
<li>Updated the config file to avoid common pitfalls and make some things more obvious.</li>
<li>Fixed some compiler warnings</li>
<li>Fixed autogen.sh to work properly on Mac OS</li>
<li>Fixed JSON access by adding support for global and mount specific custom HTTP headers.
<ul>
<li>The purpose is to fix JSON access from browsers, by supporting basic CORS use cases. This is both important for some HTML5 <code>&lt;audio&gt;</code> or <code>&lt;video&gt;</code> use cases and accessing the JSON status API.</li>
<li>The default icecast config contains the very permissive global header: &lt;header name="Access-Control-Allow-Origin" value="*" /&gt;</li>
</ul>
</li>
</ul>
<h4 id="known-issues">Known issues</h4>
<ul>
<li>HTTP PUT implementation currently doesn’t support chunked encoding yet.</li>
<li>HTTP PUT with “Expect: 100-Continue” receives first a “100” and soon after a “200”, instead of the “200” at the end of transmission.</li>
<li>Caution should be exercised when using <code>&lt;on-connect&gt;</code> or <code>&lt;on-disconnect&gt;</code>, 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.</li>
<li>Don’t use comments inside <code>&lt;http-headers&gt;</code> as it will prevent processing of further <code>&lt;header&gt;</code> tags.</li>
</ul>
</div>
<div id="v2.4.0" class="article">
<h3 id="version-240">Version 2.4.0</h3>
<h4 id="new-features">New Features</h4>
<ul>
<li>Support for Ogg Opus streams</li>
<li>Support for WebM streams</li>
<li>HTTP 1.1 PUT support for source connections. Deprecating SOURCE method</li>
<li><em>Default mount</em><br />
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.</li>
<li><em>Web interface redone</em>
<ul>
<li>Web output properly redone, credit to ePirat</li>
<li>Added <code>&lt;audio&gt;</code> element for supported audio streams</li>
<li>Now validates completely as XHTML1.0 strict</li>
<li>Also improves rendering on mobile devices</li>
</ul>
</li>
<li>Added basic JSON API (<code>/status-json.xsl</code>) based on a xml2json template by Doeke Zanstra (see <code>xml2json.xslt</code>). Output is roughly limited to data also visible through <code>status.xsl</code></li>
<li>Send charset in HTTP headers for everything, excluding file-serv and streams</li>
<li>Allow (standard strftime(3)) <code>%x</code> codes in <code>&lt;dump-file&gt;</code>. Disabled for Win32</li>
<li>Added <code>stream_start_iso8601</code>, <code>server_start_iso8601</code> 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</li>
<li>Now compiles for Win32 using mingw</li>
<li>Added options <code>headers</code> and <code>header_prefix</code> to URL based listener auth</li>
<li>Updated <code>listener_remove</code> handler, added <code>ip=</code> and <code>agent=</code></li>
<li>Allow full URLs to be returned by the master server</li>
</ul>
<h4 id="fixes-1">Fixes</h4>
<ul>
<li><strong>Security fix</strong>: Override supplementary groups if is used</li>
<li>Fixes for some race conditions</li>
<li>Dropped debian packaging directory as debian use their own.</li>
<li>Send proper HTTP headers in responses to clients.</li>
<li>Corrected Content-Length: header in admin (raw) requests. Thanks to paluh for reporting.</li>
<li>Escape log entries in access log</li>
<li>Fixed a memory leak. Lost headers of stream because of wrong ref counter in associated refbuf objects.</li>
<li>Avoid memory leak in <code>_parse_mount()</code> when <code>type</code>-attribute is set</li>
<li>Updated web interface to be XHTML compliant.</li>
<li>Removed <code>status2.xsl</code> from release. It was only a broken example file anyway.</li>
</ul>
<h4 id="known-issues-1">Known issues</h4>
<ul>
<li>Will crash if certain config tags are left empty</li>
</ul>
</div>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

783
doc/config-file.html
View File

@ -1,783 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Config File</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Config File</h2>
<div class="article">
<h3 id="overview">Overview</h3>
<p>This section will describe each section of the config file and is grouped into the following sections:</p>
<ul>
<li><a href="#limits">Limits</a></li>
<li><a href="#authentication">Authentication</a></li>
<li><a href="#yp">Stream Directory Settings</a></li>
<li><a href="#misc">Misc Server settings</a></li>
<li><a href="#ports">TCP-Port settings</a></li>
<li><a href="#global-headers">Global HTTP Headers</a></li>
<li><a href="#relay">Relay settings</a></li>
<li><a href="#mountsettings">Mount Specific settings</a></li>
<li><a href="#path">File path settings</a></li>
<li><a href="#log">Logging</a></li>
<li><a href="#security">Security</a></li>
</ul>
</div>
<div class="article">
<h3 id="a-word-of-warning">A word of warning</h3>
<p>Please note that, especially for new Icecast users, editing the config file can be quite tricky.
<strong>It is thus recommended to make a backup of the original config file and then start by just changing all
passwords, nothing else.</strong> You can then use the source-password to bring up an initial stream and get more
comfortable with how Icecast works. </p>
<p>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.</p>
<pre><code>xmllint icecast.xml
</code></pre>
<p>Also check the Icecast error.log for additional hints in case of all problems!</p>
</div>
<div class="article">
<h3 id="limits">Limits</h3>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;limits&gt;</span>
<span class="nt">&lt;clients&gt;</span>100<span class="nt">&lt;/clients&gt;</span>
<span class="nt">&lt;sources&gt;</span>2<span class="nt">&lt;/sources&gt;</span>
<span class="nt">&lt;queue-size&gt;</span>102400<span class="nt">&lt;/queue-size&gt;</span>
<span class="nt">&lt;client-timeout&gt;</span>30<span class="nt">&lt;/client-timeout&gt;</span>
<span class="nt">&lt;header-timeout&gt;</span>15<span class="nt">&lt;/header-timeout&gt;</span>
<span class="nt">&lt;source-timeout&gt;</span>10<span class="nt">&lt;/source-timeout&gt;</span>
<span class="nt">&lt;burst-on-connect&gt;</span>1<span class="nt">&lt;/burst-on-connect&gt;</span>
<span class="nt">&lt;burst-size&gt;</span>65536<span class="nt">&lt;/burst-size&gt;</span>
<span class="nt">&lt;/limits&gt;</span></code></pre></div>
<p>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.</p>
<dl>
<dt>clients</dt>
<dd>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).</dd>
<dt>sources</dt>
<dd>Maximum number of connected sources supported by the server. This includes active relays and source clients</dd>
<dt>queue-size</dt>
<dd>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.</dd>
<dt>client-timeout</dt>
<dd>This does not seem to be used.</dd>
<dt>header-timeout</dt>
<dd>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.</dd>
<dt>source-timeout</dt>
<dd>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.</dd>
<dt>burst-on-connect</dt>
<dd>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 <code>burst-size</code> instead.</dd>
<dt>burst-size</dt>
<dd>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.</dd>
</dl>
</div>
<div class="article">
<h3 id="authentication">Authentication</h3>
<!-- FIXME -->
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;authentication&gt;</span>
<span class="nt">&lt;source-password&gt;</span>hackme<span class="nt">&lt;/source-password&gt;</span>
<span class="nt">&lt;relay-user&gt;</span>relay<span class="nt">&lt;/relay-user&gt;</span>
<span class="nt">&lt;relay-password&gt;</span>hackme<span class="nt">&lt;/relay-password&gt;</span>
<span class="nt">&lt;admin-user&gt;</span>admin<span class="nt">&lt;/admin-user&gt;</span>
<span class="nt">&lt;admin-password&gt;</span>hackme<span class="nt">&lt;/admin-password&gt;</span>
<span class="nt">&lt;/authentication&gt;</span></code></pre></div>
<!-- FIXME -->
<p>This section contains all the usernames and passwords used for administration purposes or to connect sources and relays.</p>
<!-- FIXME -->
<dl>
<dt>role</dt>
<dd>contains role definitions</dd>
</dl>
<!-- FIXME -->
<dl>
<dt>source-password</dt>
<dd>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.</dd>
</dl>
<!-- FIXME -->
<dl>
<dt>relay-user</dt>
<dd>Used in the master server as part of the authentication when a slave requests the list of streams
to relay. The default username is <code>relay</code></dd>
</dl>
<!-- FIXME -->
<dl>
<dt>relay-password</dt>
<dd>Used in the master server as part of the authentication when a slave requests the list of streams to relay.</dd>
</dl>
<!-- FIXME -->
<dl>
<dt>admin-user/admin-password</dt>
<dd>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.</dd>
</dl>
</div>
<div class="article">
<h3 id="yp">Stream Directory Settings</h3>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;directory&gt;</span>
<span class="nt">&lt;yp-url-timeout&gt;</span>15<span class="nt">&lt;/yp-url-timeout&gt;</span>
<span class="nt">&lt;yp-url&gt;</span>http://dir.xiph.org/cgi-bin/yp-cgi<span class="nt">&lt;/yp-url&gt;</span>
<span class="nt">&lt;/directory&gt;</span></code></pre></div>
<p>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.</p>
<dl>
<dt>yp-url-timeout</dt>
<dd>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.</dd>
<dt>yp-url</dt>
<dd>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.</dd>
</dl>
</div>
<div class="article">
<h3 id="misc">Misc Server Settings</h3>
<h4 id="server-wide-settings">Server wide settings</h4>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;hostname&gt;</span>localhost<span class="nt">&lt;/hostname&gt;</span>
<span class="nt">&lt;location&gt;</span>earth<span class="nt">&lt;/location&gt;</span>
<span class="nt">&lt;admin&gt;</span>icemaster@localhost<span class="nt">&lt;/admin&gt;</span>
<span class="nt">&lt;fileserve&gt;</span>1<span class="nt">&lt;/fileserve&gt;</span>
<span class="nt">&lt;server-id&gt;</span>icecast 2.5<span class="nt">&lt;/server-id&gt;</span></code></pre></div>
<dl>
<dt>hostname</dt>
<dd>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.</dd>
<dt>location</dt>
<dd>This sets the location string for this Icecast instance. It will be shown e.g in the web interface.</dd>
<dt>admin</dt>
<dd>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.</dd>
<dt>fileserve</dt>
<dd>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 <code>&lt;paths&gt;&lt;webroot&gt;</code> 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.</dd>
<dt>server-id</dt>
<dd>This optional setting allows for the administrator of the server to override the default
server identification. The default is <code>icecast</code> 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.</dd>
</dl>
</div>
<div class="article">
<h3 id="ports">TCP Port settings</h3>
<p>The following shows how you can specify the listening settings for the server.</p>
<h4 id="generic-port-setup">Generic port setup</h4>
<p>The first shows an example of a common and simple way to define a listening socket:</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;listen-socket&gt;</span>
<span class="nt">&lt;port&gt;</span>8000<span class="nt">&lt;/port&gt;</span>
<span class="nt">&lt;/listen-socket&gt;</span></code></pre></div>
<p>Using this as a basis we can extend this with an <code>&lt;bind-address&gt;</code> 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 <code>&lt;ssl&gt;</code> 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. </p>
<h4 id="backward-compatibility-with-shoutcast-source-clients">Backward compatibility with Shoutcast source clients</h4>
<p>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.</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;listen-socket&gt;</span>
<span class="nt">&lt;port&gt;</span>8000<span class="nt">&lt;/port&gt;</span>
<span class="nt">&lt;shoutcast-mount&gt;</span>/live.mp3<span class="nt">&lt;/shoutcast-mount&gt;</span>
<span class="nt">&lt;/listen-socket&gt;</span></code></pre></div>
<p>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. </p>
<h4 id="old-style-shoutcast-source-client-compatible-setup-deprecated">Old style Shoutcast source client compatible setup (deprecated)</h4>
<p>The following is just to show the longer approach to defining shoutcast compatability.</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;shoutcast-mount&gt;</span>/live.nsv<span class="nt">&lt;/shoutcast-mount&gt;</span>
<span class="c">&lt;!-- You may have multiple &lt;listen-socket&gt; elements --&gt;</span>
<span class="nt">&lt;listen-socket&gt;</span>
<span class="nt">&lt;port&gt;</span>8000<span class="nt">&lt;/port&gt;</span>
<span class="nt">&lt;/listen-socket&gt;</span>
<span class="nt">&lt;listen-socket&gt;</span>
<span class="nt">&lt;port&gt;</span>8001<span class="nt">&lt;/port&gt;</span>
<span class="nt">&lt;shoutcast-compat&gt;</span>1<span class="nt">&lt;/shoutcast-compat&gt;</span>
<span class="nt">&lt;/listen-socket&gt;</span></code></pre></div>
<p>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.</p>
<dl>
<dt>port</dt>
<dd>The TCP port that will be used to accept client connections.</dd>
<dt>bind-address</dt>
<dd>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.</dd>
<dt>ssl</dt>
<dd>If set to 1 will enable HTTPS on this listen-socket. Icecast must have been compiled against openSSL to be able to do so.</dd>
<dt>shoutcast-mount</dt>
<dd>An optional mountpoint setting to be used when shoutcast DSP compatible clients connect. The default global setting
is <code>/stream</code> but can be overridden here to use an alternative name which may include an extension that some clients
require for certain formats.<br />
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 <code>shoutcast-compat</code> approach as this implicitly
defines the second listening socket and allows for specifying multiple sockets using different mountpoints for
shoutcast source clients. The <code>shoutcast-mount</code> outside of a <code>listen-socket</code> group is the global setting of the
mountpoint to use.</dd>
<dt>shoutcast-compat</dt>
<dd>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
<code>shoutcast-compat</code>. This means if you define <code>8001</code> as <code>shoutcast-compat</code>, then you will need to define a listen port
of <code>8000</code> and it must not also be defined as <code>shoutcast-compat</code>. See the example config file in the distribution for more info.</dd>
</dl>
</div>
<div class="article">
<h3 id="global-headers">Global HTTP headers</h3>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;http-headers&gt;</span>
<span class="nt">&lt;header</span> <span class="na">name=</span><span class="s">&quot;Access-Control-Allow-Origin&quot;</span> <span class="na">value=</span><span class="s">&quot;*&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;header</span> <span class="na">name=</span><span class="s">&quot;X-Robots-Tag&quot;</span> <span class="na">value=</span><span class="s">&quot;index, noarchive&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;header</span> <span class="na">name=</span><span class="s">&quot;foo&quot;</span> <span class="na">value=</span><span class="s">&quot;bar&quot;</span> <span class="na">status=</span><span class="s">&quot;200&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;header</span> <span class="na">name=</span><span class="s">&quot;Nelson&quot;</span> <span class="na">value=</span><span class="s">&quot;Ha-Ha!&quot;</span> <span class="na">status=</span><span class="s">&quot;404&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/http-headers&gt;</span></code></pre></div>
<p>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.</p>
<p>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.</p>
<dl>
<dt>http-headers</dt>
<dd>This element is placed anywhere inside the main section of the Icecast config. It will contain <code>&lt;header&gt;</code> child elements, that specify the actual headers one by one.</dd>
<dt>header</dt>
<dd>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:
<ul>
<li><code>name</code> is required and its value specifies the HTTP header field name.</li>
<li><code>value</code> is required and its value specifies the HTTP header field value.</li>
<li><code>status</code> 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.</li>
</ul>
</dd>
</dl>
<p>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 <code>&lt;http-headers&gt;</code> as, in this release, it will prevent Icecast from parsing further <code>&lt;header&gt;</code> tags.</p>
</div>
<div class="article">
<h3 id="relay">Relaying Streams</h3>
<p>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.<br />
There are two types of relay setups:<br />
a “Master server relay” or a “Specific Mountpoint relay.”</p>
<h4 id="master-relay">Master Relay</h4>
<p>A Master server relay is only supported between Icecast servers and is used to relay a number of
mountpoints from a remote Icecast server.</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;master-server&gt;</span>127.0.0.1<span class="nt">&lt;/master-server&gt;</span>
<span class="nt">&lt;master-server-port&gt;</span>8001<span class="nt">&lt;/master-server-port&gt;</span>
<span class="nt">&lt;master-update-interval&gt;</span>120<span class="nt">&lt;/master-update-interval&gt;</span>
<span class="nt">&lt;master-username&gt;</span>relay<span class="nt">&lt;/master-username&gt;</span>
<span class="nt">&lt;master-password&gt;</span>hackme<span class="nt">&lt;/master-password&gt;</span>
<span class="nt">&lt;relays-on-demand&gt;</span>0<span class="nt">&lt;/relays-on-demand&gt;</span></code></pre></div>
<p>The following diagram shows the basics of using a Master relay.<br />
Please note that the slave is configured with the <code>&lt;master-server&gt;</code>, <code>&lt;master-server-port&gt;</code>, 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. </p>
<p><img src="img/masterslave.png" alt="Master-Slave server diagram" /></p>
<p>A server is configured as a Master Server relay by specifying the <code>&lt;master-server&gt;</code>, <code>&lt;master-server-port&gt;</code>,
<code>&lt;master-update-interval&gt;</code>, <code>&lt;master-password&gt;</code> values in the config file. The server that is being relayed
does not need any special configuration.</p>
<dl>
<dt>master-server</dt>
<dd>This is the IP for the server which contains the mountpoints to be relayed (Master Server).</dd>
<dt>master-server-port</dt>
<dd>This is the TCP Port for the server which contains the mountpoints to be relayed (Master Server).</dd>
<dt>master-update-interval</dt>
<dd>The interval (in seconds) that the Relay Server will poll the Master Server for any new mountpoints to relay.</dd>
<dt>master-username</dt>
<dd>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 <code>relay</code> is used.</dd>
<dt>master-password</dt>
<dd>This is the relay password on the Master server. It is used to query the server for a list of mountpoints to
relay.</dd>
<dt>relays-on-demand</dt>
<dd>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. </dd>
</dl>
<h4 id="specific-mountpoint-relay">Specific Mountpoint Relay</h4>
<p>If only specific mountpoints need to be relayed, then you can configure Icecast with a “Specific Mountpoint Relay”.</p>
<p>The following diagram shows the basics of using a Specific Mountpoint relay. Note that the relaying Icecast is
configured with the <code>&lt;relay&gt;</code> 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. </p>
<p><img src="img/relay.png" alt="Relay server diagram" /></p>
<p>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 <code>&lt;relay&gt;</code> XML chunk in the config file
for each mountpoint to be relayed. The server that is being relayed does not need any special configuration.</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;relay&gt;</span>
<span class="nt">&lt;server&gt;</span>127.0.0.1<span class="nt">&lt;/server&gt;</span>
<span class="nt">&lt;port&gt;</span>8001<span class="nt">&lt;/port&gt;</span>
<span class="nt">&lt;mount&gt;</span>/example.ogg<span class="nt">&lt;/mount&gt;</span>
<span class="nt">&lt;local-mount&gt;</span>/different.ogg<span class="nt">&lt;/local-mount&gt;</span>
<span class="nt">&lt;username&gt;</span>joe<span class="nt">&lt;/username&gt;</span>
<span class="nt">&lt;password&gt;</span>soap<span class="nt">&lt;/password&gt;</span>
<span class="nt">&lt;relay-shoutcast-metadata&gt;</span>0<span class="nt">&lt;/relay-shoutcast-metadata&gt;</span>
<span class="nt">&lt;on-demand&gt;</span>1<span class="nt">&lt;/on-demand&gt;</span>
<span class="nt">&lt;/relay&gt;</span></code></pre></div>
<dl>
<dt>server</dt>
<dd>This is the IP for the server which contains the mountpoint to be relayed.</dd>
<dt>port</dt>
<dd>This is the TCP Port for the server which contains the mountpoint to be relayed.</dd>
<dt>mount</dt>
<dd>The mountpoint located on the remote server. If you are relaying a shoutcast stream,
this should be a <code>/</code> or <code>/name</code>.</dd>
<dt>local-mount</dt>
<dd>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.</dd>
<dt>username</dt>
<dd>The source of the relay may require authentication itself, if so state the username here.</dd>
<dt>password</dt>
<dd>The source of the relay may require authentication itself, if so state the password here.</dd>
<dt>relay-shoutcast-metadata</dt>
<dd>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.<br />
<code>1</code>: enabled, <code>0</code>: disabled</dd>
<dt>on-demand</dt>
<dd>An on-demand relay will only retrieve the stream if there are listeners requesting the stream.
<code>1</code>: enabled, <code>0</code>: disabled (default is <code>&lt;relays-on-demand&gt;</code>). This is useful in cases where you want to
limit bandwidth costs when no one is listening.</dd>
</dl>
</div>
<div class="article">
<h3 id="mountsettings">Mount Specific Settings</h3>
<!-- FIXME -->
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;mount</span> <span class="na">type=</span><span class="s">&quot;normal&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;mount-name&gt;</span>/example-complex.ogg<span class="nt">&lt;/mount-name&gt;</span>
<span class="nt">&lt;username&gt;</span>othersource<span class="nt">&lt;/username&gt;</span>
<span class="nt">&lt;password&gt;</span>hackmemore<span class="nt">&lt;/password&gt;</span>
<span class="nt">&lt;max-listeners&gt;</span>1<span class="nt">&lt;/max-listeners&gt;</span>
<span class="nt">&lt;max-listener-duration&gt;</span>3600<span class="nt">&lt;/max-listener-duration&gt;</span>
<span class="nt">&lt;dump-file&gt;</span>/tmp/dump-example1.ogg<span class="nt">&lt;/dump-file&gt;</span>
<span class="nt">&lt;intro&gt;</span>/intro.ogg<span class="nt">&lt;/intro&gt;</span>
<span class="nt">&lt;fallback-mount&gt;</span>/example2.ogg<span class="nt">&lt;/fallback-mount&gt;</span>
<span class="nt">&lt;fallback-override&gt;</span>1<span class="nt">&lt;/fallback-override&gt;</span>
<span class="nt">&lt;fallback-when-full&gt;</span>1<span class="nt">&lt;/fallback-when-full&gt;</span>
<span class="nt">&lt;charset&gt;</span>ISO8859-1<span class="nt">&lt;/charset&gt;</span>
<span class="nt">&lt;public&gt;</span>1<span class="nt">&lt;/public&gt;</span>
<span class="nt">&lt;stream-name&gt;</span>My audio stream<span class="nt">&lt;/stream-name&gt;</span>
<span class="nt">&lt;stream-description&gt;</span>My audio description<span class="nt">&lt;/stream-description&gt;</span>
<span class="nt">&lt;stream-url&gt;</span>http://some.place.com<span class="nt">&lt;/stream-url&gt;</span>
<span class="nt">&lt;genre&gt;</span>classical<span class="nt">&lt;/genre&gt;</span>
<span class="nt">&lt;bitrate&gt;</span>64<span class="nt">&lt;/bitrate&gt;</span>
<span class="nt">&lt;type&gt;</span>application/ogg<span class="nt">&lt;/type&gt;</span>
<span class="nt">&lt;subtype&gt;</span>vorbis<span class="nt">&lt;/subtype&gt;</span>
<span class="nt">&lt;hidden&gt;</span>1<span class="nt">&lt;/hidden&gt;</span>
<span class="nt">&lt;burst-size&gt;</span>65536<span class="nt">&lt;/burst-size&gt;</span>
<span class="nt">&lt;mp3-metadata-interval&gt;</span>4096<span class="nt">&lt;/mp3-metadata-interval&gt;</span>
<span class="nt">&lt;authentication</span> <span class="na">type=</span><span class="s">&quot;xxxxxx&quot;</span><span class="nt">&gt;</span>
<span class="c">&lt;!-- See authentication documentation --&gt;</span>
<span class="nt">&lt;/authentication&gt;</span>
<span class="nt">&lt;http-headers&gt;</span>
<span class="nt">&lt;header</span> <span class="na">name=</span><span class="s">&quot;Access-Control-Allow-Origin&quot;</span> <span class="na">value=</span><span class="s">&quot;*&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;header</span> <span class="na">name=</span><span class="s">&quot;X-Robots-Tag&quot;</span> <span class="na">value=</span><span class="s">&quot;index, noarchive&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;header</span> <span class="na">name=</span><span class="s">&quot;foo&quot;</span> <span class="na">value=</span><span class="s">&quot;bar&quot;</span> <span class="na">status=</span><span class="s">&quot;200&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;header</span> <span class="na">name=</span><span class="s">&quot;Nelson&quot;</span> <span class="na">value=</span><span class="s">&quot;Ha-Ha!&quot;</span> <span class="na">status=</span><span class="s">&quot;404&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/http-headers&gt;</span>
<span class="nt">&lt;on-connect&gt;</span>/home/icecast/bin/source-start<span class="nt">&lt;/on-connect&gt;</span>
<span class="nt">&lt;on-disconnect&gt;</span>/home/icecast/bin/source-end<span class="nt">&lt;/on-disconnect&gt;</span>
<span class="nt">&lt;/mount&gt;</span></code></pre></div>
<p>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.</p>
<p>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.</p>
<dl>
<dt>type</dt>
<dd>The type of the mount point (default: “normal”). A mount of type “default”
can be used to specify common values for multiple mountpoints.<br />
Note that default mountpoints won’t merge with other mount blocks.
You only get those values if no <code>type="normal"</code> mount block exists
corresponding to your mountpoint.</dd>
<dt>mount-name</dt>
<dd>The name of the mount point for which these settings apply.
MUST NOT be used in case of mount type “default”.</dd>
</dl>
<!-- FIXME -->
<dl>
<dt>username</dt>
<dd>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 <code>source</code>.<br />
If this value is not present the default username is <code>source</code>.</dd>
</dl>
<!-- FIXME -->
<dl>
<dt>password</dt>
<dd>An optional value which will set the password that a source must use to connect using this mountpoint.
There is also a <a href="auth.html#stream-auth">URL based authentication method</a> for sources that can be used instead.</dd>
<dt>max-listeners</dt>
<dd>An optional value which will set the maximum number of listeners that can be attached to this mountpoint.</dd>
<dt>max-listener-duration</dt>
<dd>An optional value which will set the length of time a listener will stay connected to the stream.<br />
An auth component may override this.</dd>
<dt>dump-file</dt>
<dd>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 <code>%F</code>.</dd>
<dt>intro</dt>
<dd>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.</dd>
<dt>fallback-mount</dt>
<dd>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.<br />
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.<br />
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.<br />
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.</dd>
<dt>fallback-override</dt>
<dd>When enabled, this allows a connecting source client or relay on this mountpoint to move listening
clients back from the fallback mount.</dd>
<dt>fallback-when-full</dt>
<dd>When set to <code>1</code>, 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.</dd>
<dt><del>no-yp</del> (deprecated)</dt>
<dd>Setting this option prevents this mountpoint from advertising on YP. The default is <code>0</code> so YP advertising
can occur however you may want to prevent it here if you intend listeners to connect to a local relay instead.<br />
Deprecated option, replaced by <code>&lt;public&gt;</code></dd>
<dt>charset</dt>
<dd>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.<br />
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.<br />
The source clients can also specify a <code>charset=</code> parameter to the metadata update URL if they so wish.</dd>
<dt>public</dt>
<dd>The default setting for this is <code>-1</code> indicating that it is up to the source client or relay to determine if this mountpoint
should advertise. A setting of <code>0</code> will prevent any advertising and a setting of <code>1</code> 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.</dd>
<dt>stream-name</dt>
<dd>Setting this will add the specified name to the stats (and therefore YP) for this mountpoint even if the source client/relay provide one.</dd>
<dt>stream-description</dt>
<dd>Setting this will add the specified description to the stats (and therefore YP) for this mountpoint even if the source client/relay provide one.</dd>
<dt>stream-url</dt>
<dd>Setting this will add the specified URL to the stats (and therefore YP) for this mountpoint even if the source client/relay provide one.<br />
The URL is generally for directing people to a website.</dd>
<dt>genre</dt>
<dd>Setting this will add the specified genre to the stats (and therefore YP) for this mountpoint even if the source client/relay provide one.<br />
This can be anything be using certain key words can help searches in the YP directories.</dd>
<dt>bitrate</dt>
<dd>Setting this will add the specified bitrate to the stats (and therefore YP) for this mountpoint even if the source client/relay provide one.<br />
This is stated in kbps.</dd>
<dt>type</dt>
<dd>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.<br />
It is very unlikely that this will be needed.</dd>
<dt>subtype</dt>
<dd>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</dd>
<dt>burst-size</dt>
<dd>This optional setting allows for providing a burst size which overrides the default burst size as defined in limits.<br />
The value is in bytes.</dd>
<dt>mp3-metadata-interval</dt>
<dd>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.</dd>
<dt>hidden</dt>
<dd>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.</dd>
</dl>
<!-- FIXME -->
<dl>
<dt>authentication</dt>
<dd>This specifies that the named mount point will require listener (or source) authentication. Currently, we support a file-based
authentication scheme (<code>type=htpasswd</code>) 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.<br />
You can read more about authentication and URL based source authentication <a href="auth.html">here</a>.</dd>
<dt>http-headers</dt>
<dd>This element is placed anywhere inside the mount section of the icecast config. It will contain <code>&lt;header&gt;</code> child elements, that specify the actual HTTP headers one by one.</dd>
<dt>header</dt>
<dd>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:
<ul>
<li><code>name</code> is required and its value specifies the HTTP header field name.</li>
<li><code>value</code> is required and its value specifies the HTTP header field value.</li>
</ul>
</dd>
<dt>on-connect</dt>
<dd>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.
<em>This option is not available on Win32</em></dd>
<dt>on-disconnect</dt>
<dd>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.<br />
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.
<em>This option is not available on Win32</em></dd>
</dl>
</div>
<div class="article">
<h3 id="path">Path Settings</h3>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;paths&gt;</span>
<span class="nt">&lt;basedir&gt;</span>./<span class="nt">&lt;/basedir&gt;</span>
<span class="nt">&lt;logdir&gt;</span>./logs<span class="nt">&lt;/logdir&gt;</span>
<span class="nt">&lt;pidfile&gt;</span>./icecast.pid<span class="nt">&lt;/pidfile&gt;</span>
<span class="nt">&lt;webroot&gt;</span>./web<span class="nt">&lt;/webroot&gt;</span>
<span class="nt">&lt;adminroot&gt;</span>./admin<span class="nt">&lt;/adminroot&gt;</span>
<span class="nt">&lt;allow-ip&gt;</span>/path/to/ip_allowlist<span class="nt">&lt;/allow-ip&gt;</span>
<span class="nt">&lt;deny-ip&gt;</span>/path_to_ip_denylist<span class="nt">&lt;/deny-ip&gt;</span>
<span class="nt">&lt;ssl-certificate&gt;</span>/path/to/certificate.pem<span class="nt">&lt;/ssl-certificate&gt;</span>
<span class="nt">&lt;ssl-allowed-ciphers&gt;</span>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<span class="nt">&lt;/ssl-allowed-ciphers&gt;</span>
<span class="nt">&lt;alias</span> <span class="na">source=</span><span class="s">&quot;/foo&quot;</span> <span class="na">dest=</span><span class="s">&quot;/bar&quot;</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/paths&gt;</span></code></pre></div>
<p>This section contains paths which are used for various things within icecast. All paths (other than any aliases) should not end in a <code>/</code>.</p>
<dl>
<dt>basedir</dt>
<dd>This path is used in conjunction with the chroot settings, and specifies the base directory that is chrooted to when the server is started.<br />
<em>This feature is not supported on Win32.</em></dd>
<dt>logdir</dt>
<dd>This path specifies the base directory used for logging. Both the <code>error.log</code> and <code>access.log</code> will be created relative to this directory.</dd>
<dt>pidfile</dt>
<dd>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.<br />
This could be read and used for sending signals to Icecast.</dd>
<dt>webroot</dt>
<dd>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 <code>/var/share/icecast2</code>, and a request for
<code>http://server:port/mp3/stuff.mp3</code> comes in, then the file <code>/var/share/icecast2/mp3/stuff.mp3</code> will be served.</dd>
<dt>adminroot</dt>
<dd>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.</dd>
<dt>allow-ip</dt>
<dd>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.<br />
The format of the file is simple, one IP per line.</dd>
<dt>deny-ip</dt>
<dd>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.<br />
The format of the file is simple, one IP per line.</dd>
</dl>
<!-- FIXME -->
<dl>
<dt>alias</dt>
<dd>Aliases are used to provide a way to create multiple mountpoints that refer to the same mountpoint.<br />
For example: <code>&lt;alias source="/foo" dest="/bar"&gt;</code></dd>
<dt>ssl-certificate</dt>
<dd>If specified, this points to the location of a file that contains <em>both</em> 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.</dd>
<dt>ssl-allowed-ciphers</dt>
<dd>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 <em>only</em> override those, using this tag, if you know exactly what you are doing.</dd>
</dl>
</div>
<div class="article">
<h3 id="log">Logging Settings</h3>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;logging&gt;</span>
<span class="nt">&lt;accesslog&gt;</span>access.log<span class="nt">&lt;/accesslog&gt;</span>
<span class="nt">&lt;errorlog&gt;</span>error.log<span class="nt">&lt;/errorlog&gt;</span>
<span class="nt">&lt;playlistlog&gt;</span>playlist.log<span class="nt">&lt;/playlistlog&gt;</span>
<span class="nt">&lt;loglevel&gt;</span>4<span class="nt">&lt;/loglevel&gt;</span> <span class="c">&lt;!-- 4 Debug, 3 Info, 2 Warn, 1 Error --&gt;</span>
<span class="nt">&lt;/logging&gt;</span></code></pre></div>
<p>This section contains information relating to logging within Icecast. There are three logfiles currently generated by Icecast,
an <code>error.log</code> (where all log messages are placed), an <code>access.log</code> (where all stream/admin/http requests are logged) and an
optional <code>playlist.log</code>. </p>
<p>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. </p>
<p>If you set any of the filenames to a simple dash (e.g. <code>&lt;accesslog&gt;-&lt;/accesslog&gt;</code>) then Icecast will direct the log output to
STDERR instead of a file.</p>
<dl>
<dt>accesslog</dt>
<dd>Into this file, all requests made to the icecast2 will be logged. This file is relative to the path specified by the <code>&lt;logdir&gt;</code> config value.</dd>
<dt>errorlog</dt>
<dd>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.</dd>
<dt>playlistlog</dt>
<dd>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.</dd>
<dt>logsize</dt>
<dd>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 <code>logfile.old</code>, or add a timestamp to the archived file (if logarchive is enabled).</dd>
<dt>logarchive</dt>
<dd>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 <code>logfile.old</code> (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.</dd>
<dt>loglevel</dt>
<dd>Indicates what messages are logged by icecast. Log messages are categorized into one of 4 types, Debug, Info, Warn, and Error.<br />
<p>The following mapping can be used to set the appropriate value:</p>
<ul>
<li>loglevel = <code>4</code>: Debug, Info, Warn, Error messages are printed</li>
<li>loglevel = <code>3</code>: Info, Warn, Error messages are printed</li>
<li>loglevel = <code>2</code>: Warn, Error messages are printed</li>
<li>loglevel = <code>1</code>: Error messages only are printed</li>
</ul>
</dd>
</dl>
</div>
<div class="article">
<h3 id="security">Security Settings</h3>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;security&gt;</span>
<span class="nt">&lt;chroot&gt;</span>0<span class="nt">&lt;/chroot&gt;</span>
<span class="nt">&lt;changeowner&gt;</span>
<span class="nt">&lt;user&gt;</span>nobody<span class="nt">&lt;/user&gt;</span>
<span class="nt">&lt;group&gt;</span>nogroup<span class="nt">&lt;/group&gt;</span>
<span class="nt">&lt;/changeowner&gt;</span>
<span class="nt">&lt;/security&gt;</span></code></pre></div>
<p>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.
<em>This is currently not supported on Win32.</em></p>
<dl>
<dt>chroot</dt>
<dd>An indicator which specifies whether a <code>chroot()</code> will be done when the server is started.
The chrooted path is specified by the <code>&lt;basedir&gt;</code> configuration value.
Setting up and using a chroot is an advanced concept and not in the scope of this document.</dd>
<dt>changeowner</dt>
<dd>This section indicates the user and group that will own the icecast process when it is started.<br />
These need to be valid users on the system. Icecast must be started as root for this to work.</dd>
</dl>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

97
doc/docs/admin_interface.md Normal file
View File

@ -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 `<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.
# 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.

359
doc/docs/auth.md Normal file
View File

@ -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 `<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:
<!-- FIXME -->
* 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 `<mount>` section in the main icecast config file. The following is an example:
<!-- FIXME -->
```xml
<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](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 `<mount>` section in the main Icecast config file. The following shows the list of options available:
<!-- FIXME -->
```xml
<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="foobar"/>
<option name="password" value="hackmeevenmore"/>
<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.
<!-- FIXME -->
## 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.
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 `<mount>` group relating to the mountpoint.
The following authentication mechanisms can apply to sources:
<!-- FIXME -->
* BASIC: `<password>` and possibly `<username>` in the `<mount>` section
* URL: issue web requests (eg. PHP) to match authentication
## 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`

66
doc/docs/basic_setup.md Normal file
View File

@ -0,0 +1,66 @@
# 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.
As already explained in the Introduction, there are two major components involved: The streaming server (Icecast in this case) and the source client.
The following diagram shows how Icecast works:
![Icecast Shema Diagram](img/Icecast_shema.svg)
A Source Client (i.e. IceS, RoarAudio, …) connects to a mountpoint on the Icecast server and sends audio or video data to it. Listeners connect to the mountpoint and Icecast send the stream to them.
The Icecast server will be the place where all listeners of your stream will connect. The source client (in general) runs on a separate machine than Icecast, but does not necessarily need to.
# The Basics
Each Icecast server can house multiple streams, we call these mountpoints. A mountpoint is a unique name on your server identifying a particular stream - it looks like a filename, such as /stream.ogg and a listener can only listen to a single mountpoint at a time. This means you can have a single Icecast server contain 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.
# Setting up Icecast
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 install the Icecast server itself. The recommended way to do this is using the distro packages, or in case of Win32 download the binary package or installer. How to do this is not contained within this documentation.
After installation there is placed a sample config file named `icecast.xml` in either `/usr/local/etc`, `/etc/` or `/etc/icecast2/` (for UNIX) or in the current working directory, in a folder called `etc`, in case you are using the Window binary package.
The next step is to edit the `icecast.xml` config 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)
If you expect many listeners, make sure to adjust the `<clients>` limit in the `<limits>` block.
Additionally make sure to note where the Icecast log file is stored, see the `<logdir>` value in the `<paths>` section.
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 in the log directory for the ‘server started’ message, it will look something like:
[2014-11-20 19:17:48] INFO main/main Icecast 2.4.1 server started
You may notice slight variations to the line above, but the key thing here is that the server is started, logging is working and the version is shown.
You can also verify that Icecast is started by visiting the following URL [http://localhost:8000/admin/stats.xsl](http://localhost:8000/admin/stats.xsl) on the machine running Icecast. Replace localhost with the correct hostname and adjust the port, if you aren't using the default port 8000.
You should be prompted for a username and password. Enter the username `admin` and the password you entered for `<admin-password>` in the config. If all is well, you should see a Status Page which represents Icecast statistics (more about that later).
# Setting up the Source Client
Now that the Icecast server is started you must configure your source client. The information you will need for the source client is the following:
- Hostname (or 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 mountpoint (although you can configure settings for specific mountpoint, this is covered on Advanced configuration), 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.xsl 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` within your media player.
Alternatively you can use `http://192.0.2.23:8000/mystream.ogg.m3u`, (note the .m3u extension added) which will serve up a link that opens most media players. 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.

568
doc/docs/config_file.md Normal file
View File

@ -0,0 +1,568 @@
This section will describe each section of the configuration file.
!!! note
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.
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 problems!
# General Settings
```xml
<hostname>example.org</hostname>
<location>Moon</location>
<admin>icemaster@example.org</admin>
<fileserve>1</fileserve>
<server-id>icecast 2.4.1</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. This should be something
that your listeners can use.
__Note__: This should not the the URL of your stream's website or so, but the hostname for this
Icecast server!
location
: This sets the location string for this Icecast instance. It will be shown e.g on 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. on the web interface.
fileserve
: This flag turns on the Icecast fileserver from which static files can be served. All files
are served relative to the path specified in the [`<webroot>`](#path-settings) 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.
It is not recommended to use this setting, unless you have very good reasons and know
what you are doing.
# Limits
```xml
<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. Usually only the `<clients>` and `<sources>` values
need to be adjusted.
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 as well, 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 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. 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 usually not 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
This section contains all the usernames and passwords used for administration purposes or to connect sources and relays.
For more information, refer to the [Authentication](auth.md) Page.
# Public Directory Publishing Settings
```xml
<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 Directory servers.
Multiple occurances of this section can be specified in order to be listed on multiple directory servers.
For more Information see the [Listing in a Directory](yp.md) Page.
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.
# TCP Port settings
The following shows how you can specify the listening settings for the server.
```xml
<listen-socket>
<port>8000</port>
<bind-address>127.0.0.1</bind-address>
</listen-socket>
<listen-socket>
<port>8443</port>
<tls>1</tls>
</listen-socket>
<listen-socket>
<port>8004</port>
<shoutcast-mount>/live.mp3</shoutcast-mount>
</listen-socket>
```
The first listen-socket block shows how to make Icecast listen on port 8000, and additionally specifies
a `<bind-address>`, which limits this port to only listen for connections from this address.
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.
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.
The last listen-socket block in this example shows how to defined a Shoutcast compatible port. This can
be done by setting the `shoutcast-mount` setting. This will implicity define a second listening socket
whose port number is always one higher than the port defined (because the Shoutcast protocol requires
two ports) and also informs Icecast of which mountpoint the Shoutcast source client on this port will be using.
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.
tls
: 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.
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.
# HTTP headers
```xml
<http-headers>
<header name="Access-Control-Allow-Origin" value="*" />
<header name="X-Robots-Tag" value="index, noarchive" status="200" />
</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.
<dl>
<dt>http-headers</dt>
<dd>This element is placed anywhere inside the main section of the Icecast config.
It will contain <code>&lt;header&gt;</code> child elements, that specify the actual headers one by one.</dd>
<dt>header</dt>
<dd>This tag specifies the actual header to be sent to a HTTP client in response to every request.<br />
This tag can contain the following attributes:
<dl>
<dt>name</dt>
<dd>Specifies the HTTP header field name. (required)</dd>
<dt>value</dt>
<dd>Specifies the HTTP header field value. (required)</dd>
<dt>status</dt>
<dd>Limits sending the header to certain HTTP status codes.<br />
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. (optional)
</dd>
</dl>
</dd>
</dl>
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.”
For information about the two types and how to configure them, refer to the [Relaying](relaying.md) Page.
# Mount Specific Settings
<!-- FIXME -->
```xml
<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>ISO-8859-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".
<!-- FIXME -->
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`.
<!-- FIXME -->
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](auth.html#stream-auth) 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.
charset
: For legacy, 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 directory 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 directory listings) 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 directory listings) 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 directory listings) 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 directory listings) 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 directories.
bitrate
: Setting this will add the specified bitrate to the stats (and therefore directory listings) 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 directory listings) 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 directory listings) for this mountpoint.
The subtype is really to help the directory server to identify the components of the type.
An example setting is vorbis/theora and indicates 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.
<!-- FIXME -->
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](auth.html).
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
```xml
<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>
<tls-certificate>/path/to/certificate.pem</tls-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.
<!-- FIXME -->
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">`
tls-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.
tls-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
```xml
<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
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.
!!! attention
This is currently not supported on Win32.
```xml
<security>
<chroot>0</chroot>
<changeowner>
<user>nobody</user>
<group>nogroup</group>
</changeowner>
</security>
```
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.

1
doc/docs/img/Icecast_shema.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 236 KiB

67
doc/docs/index.md Normal file
View File

@ -0,0 +1,67 @@
# Icecast 2.4.1 Documentation
Icecast is a streaming media server which currently supports Ogg Vorbis and MP3 audio streams.
It can be used to create an Internet radio station or a privately running jukebox and many
things in between. It is very versatile in that new formats can be added relatively easily
and supports open standards for commuincation and interaction.
Icecast is distributed under the GNU GPL, version 2. A copy of this license is included with
this software in the COPYING file.
There are two major parts to most streaming media servers: The component providing the
content (what we call source clients) and the component which is responsible for serving that
content to listeners (this is the function of Icecast).
# Prerequisites
Icecast requires the following packages:
* [libxml2](http://xmlsoft.org/downloads.html)
* [libxslt](http://xmlsoft.org/XSLT/downloads.html)
* [curl](http://curl.haxx.se/download.html) Version >= 7.10
* [libogg/libvorbis](http://www.vorbis.com/files) Version >= 1.0
* [OpenSSL](https://www.openssl.org/source/) (Optional, enable if SSL support is desired)
# What platforms are supported?
Currently the following Unix platforms are supported:
- Linux (Most flavors including Redhat and Debian)
- FreeBSD
- OpenBSD
- Solaris
Currently the following Windows platforms are supported:
- Windows Vista
- Windows 7
- Windows 8
- Windows Server 2003
- Windows Server 2008
- Windows Server 2012
# Build/Install
To build Icecast on a Unix platform, perform the following:
Run
./configure
make
make install
to build and install this release.
A sample config file will be placed in `/usr/local/etc` (on UNIX) or in the current working
directory (on Win32) and is called `icecast.xml`.
Documentation for Icecast is available in the doc directory, by viewing `doc/index.html` in a
browser.
# Where do I go for questions?
There are many ways to contact the icecast development team, best ways are:
- The [Icecast Mailing list](http://lists.xiph.org/mailman/listinfo/icecast)
- The [Icecast Developer Mailing list](http://lists.xiph.org/mailman/listinfo/icecast-dev), for more development-related questions.
- Icecast IRC Chat at the [#icecast](irc://irc.freenode.net:6667/#icecast) channel on irc.freenode.net

33
doc/docs/introduction.md Normal file
View File

@ -0,0 +1,33 @@
# What is Icecast?
Icecast is a streaming media server which currently supports Ogg Vorbis, Opus, Theora and WebM streams, MP3 and AAC streams are known to work. It can be used to create an Internet radio station or a privately running jukebox and many things in between. It is very versatile in that new formats can be added relatively easily and supports open standards for commuincation and interaction.
There are two major parts to most streaming media servers: the component providing the content (what we call source clients) and the component which is responsible for serving that content to listeners (this is the function of icecast).
# What platforms are supported?
Currently the following Unix platforms are supported:
- Linux (Most flavors including Redhat and Debian)
- FreeBSD
- OpenBSD
- Solaris
Currently the following Windows platforms are supported:
- Windows Vista
- Windows 7
- Windows 8
- Windows Server 2003
- Windows Server 2008
- Windows Server 2012
# Where do I go for questions?
There are many ways to contact the icecast development team
Best Ways:
- Icecast mailing list [http://lists.xiph.org/mailman/listinfo/icecast](http://lists.xiph.org/mailman/listinfo/icecast)
- Icecast Developers mailing list [http://lists.xiph.org/mailman/listinfo/icecast-dev](http://lists.xiph.org/mailman/listinfo/icecast-dev)
- Icecast IRC chat room - irc.freenode.net : #icecast

111
doc/docs/relaying.md Normal file
View File

@ -0,0 +1,111 @@
Relaying is the process by which one server mirrors one or more streams from a remote server. The servers
need not be of the same type (i.e. Icecast can relay from Shoutcast). Relaying is used primarily for large
broadcasts that need to distribute listening clients across multiple physical machines.
# Type of Relays
There are two types of relays that Icecast supports:
The first type is when both master and slave servers are Icecast 2 servers. In this case, a “master-slave” relay
can be setup such that all that needs to be done is configure the slave server with the connection information
(server IP and port) of the master server and the slave will mirror all mountpoints on the master server. The slave
will also periodically check the master server to see if any new mountpoints have attached and if so will relay those
as well.
The second type of relay is a specific mountpoint relay. In this case, the slave server is configured with a
server IP, port and mountpoint and only the mountpoint specified is relayed.
# Setting Up a Master-Slave Relay
In order to setup a relay of this type both servers (the one you wish to relay and the one doing the relaying)
need to be Icecast 2 servers.
The following configuration snippet is used as an example:
```xml
<master-server>192.168.1.11</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>
```
In this example, this configuration is setup in the server which will be doing the relaying (slave server).
The master server in this case need not be configured (and actually is unaware of the relaying being performed).
When the slave server is started, it will connect to the master server, 192.168.1.11:8001 in this example. The slave server will begin to relay all non-hidden mountpoints connected to the master server. Additionally, every master-update-interval, 120 seconds
in this case, the slave server will poll the master server to see if any new mountpoints have connected.
Note that the names of the mountpoints on the slave server will be identical to those on the master server.
Configuration options:
master-server
: This is the hostname (or 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 for the master server, used to query the server for a list of mountpoints to relay.
(Defaults to `relay`)
master-password
: This is the relay password for the master server, used to query the server for a list of mounpoints 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 bandwidth costs when no one is listening.
# Specific Mountpoint Relay
If only specific mountpoints need to be relayed, or the master server is not a Icecast 2 server, you can use the specific
mountpoint relay. Supported master servers for this type of relay are Shoutcast, Icecast 1.x, and of course Icecast 2.
The following configuration snippet is used as an example:
```xml
<relay>
<server>192.168.1.11</server>
<port>8001</port>
<mount>/example.ogg</mount>
<local-mount>/different.ogg</local-mount>
<username>Jekyll</username>
<password>Hyde</password>
<relay-shoutcast-metadata>0</relay-shoutcast-metadata>
<on-demand>1</on-demand>
</relay>
```
In this example, this configuration is setup in the server which will be doing the relaying (slave server).
The master server in this case need not be configured (and actually is unaware of the relaying being performed) as a
relay. When the slave server is started, it will connect to the master server, in this example located at 192.168.1.11:8001
and will begin to relay only the mountpoint specified (/example.ogg in this case).
Using this type of relay, the user can override the local mountpoint name and make it something entirely different than the one on the master server. Additionally, if the server is a Shoutcast server, then the `<mount>` must be specified as `/`,
and if you want the Shoutcast relay stream to have metadata contained within it (Shoutcast metadata is embedded
in the stream itself), the `<relay-shoutcast-metadata>` needs to be set to `1`.
Configuration options:
server
: This is the hostname (or 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 `/`)
local-mount
: The name to use for the local mountpoint. This is what the mountpoint will be called on the relaying server. (Defaults to the remote mountpoint)
username
: The username, if required, for the remote mountpoint.
password
: The password, if required, for the remote mountpoint.
relay-shoutcast-metadata
: If relaying a Shoutcast stream, set this to `1` to relay the metadata (song titles), which are part of the Shoutcast data stream. (Defaults to enabled, but it's up to the remote server if metadata is sent)
Possible values: `1`: enabled, `0`: disabled
on-demand
: An on-demand relay will only retrieve the stream if there are listeners requesting the stream. (Defaults to the value of `<relays-on-demand>`)
Possible values: `1`: enabled, `0`: disabled

286
doc/docs/server_stats.md Normal file
View File

@ -0,0 +1,286 @@
Icecast provides extensive run time statistics. Both in the form of active connection numbers and cumulative
counters (since server startup or respectively source connection startup).
# HTML Interface
Icecast comes with a HTML web interface, it exposes a basic set of server statistics that should
fulfil basic user needs. Icecast uses the very powerful libxslt engine to transform its internal
raw statistical data into custom tailored interfaces.
Many people have written custom XSLT code that produces e.g. plain text “now playing”, XSPF, VCLT,
munin interface data, etc. If so desired, the files in webroot can be customized to contain more or less
information (see section on raw XML data below).
!!! attention
__We strongly discourage attempts to scrape data from the web interface__ as we do not consider this an
API and will change it, even completely, between versions! The preferred ways are custom XSLT, JSON and raw XML.
# JSON Stats
Since version 2.4.0 Icecast includes a basic JSON endpoint (`/status-json.xsl`) based on a xml2json template by Doeke Zanstra
(see `xml2json.xslt`). It exposes the same set of server statistics that are available through the web interface and
should fulfil basic user needs. The intention is to not break backwards compatibility of this interface in the future,
still we recommend to design robust software that can deal with possible changes like addition or removal of variables.
Also note that not all variables are available all the time and availability may change at runtime due to stream type, etc.
# Available XML data
This section contains information about the raw XML server statistics data available inside Icecast. An example
stats XML tree will be shown and each element will be described. The following example stats tree will be used:
```xml
<icestats>
<admin>icemaster@localhost</admin>
<client_connections>649</client_connections>
<clients>2</clients>
<connections>907</connections>
<file_connections>379</file_connections>
<host>localhost</host>
<listener_connections>90</listener_connections>
<listeners>0</listeners>
<location>Earth</location>
<server_id>Icecast 2.5</server_id>
<source_client_connections>164</source_client_connections>
<source_relay_connections>0</source_relay_connections>
<source_total_connections>164</source_total_connections>
<sources>2</sources>
<stats>0</stats>
<stats_connections>0</stats_connections>
<source mount="/audio.ogg">
<title>All that she wants</title>
<artist>Ace of Base</artist>
<audio_bitrate>499821</audio_bitrate>
<audio_channels>2</audio_channels>
<audio_info>samplerate=44100;quality=10%2e0;channels=2</audio_info>
<audio_samplerate>44100</audio_samplerate>
<channels>2</channels>
<genre>various</genre>
<ice-bitrate>499</ice-bitrate>
<listener_peak>0</listener_peak>
<listeners>0</listeners>
<listenurl>http://localhost:8000/audio</listenurl>
<max_listeners>unlimited</max_listeners>
<public>1</public>
<quality>10.0</quality>
<samplerate>44100</samplerate>
<server_description>Teststream</server_description>
<server_name>Great audio stream</server_name>
<server_type>application/ogg</server_type>
<server_url>http://example.org/</server_url>
<slow_listeners>0</slow_listeners>
<source_ip>192.0.2.21</source_ip>
<subtype>Vorbis</subtype>
<total_bytes_read>3372153</total_bytes_read>
<total_bytes_sent>0</total_bytes_sent>
<user_agent>LadioCast/0.10.5 libshout/2.3.1</user_agent>
</source>
<source mount="/video.ogg">
<audio_bitrate>276000</audio_bitrate>
<audio_channels>6</audio_channels>
<audio_samplerate>48000</audio_samplerate>
<frame_rate>25.00</frame_rate>
<frame_size>720 x 576</frame_size>
<genre>various</genre>
<ice-bitrate>276</ice-bitrate>
<listener_peak>0</listener_peak>
<listeners>0</listeners>
<listenurl>http://localhost:8000/video</listenurl>
<max_listeners>unlimited</max_listeners>
<public>0</public>
<server_description>Unspecified description</server_description>
<server_name>Unspecified name</server_name>
<server_type>video/ogg</server_type>
<slow_listeners>0</slow_listeners>
<source_ip>192.0.2.21</source_ip>
<subtype>Vorbis/Theora</subtype>
<title>ERAGON</title>
<total_bytes_read>37136</total_bytes_read>
<total_bytes_sent>0</total_bytes_sent>
<user_agent>Lavf/55.20.0</user_agent>
<video_bitrate>200000</video_bitrate>
<video_quality>0</video_quality>
</source>
</icestats>
```
## General Statistics
<!-- FIXME -->
admin
: As set in the server config, 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.
client_connections
: Client connections are basically anything that is not a source connection. These include listeners (not concurrent,
but cumulative), any admin function accesses, and any static content (file serving) accesses.
_This is an accumulating counter._
clients
: Number of currently active client connections.
connections
: The total of all inbound TCP connections since start-up.
_This is an accumulating counter._
file_connections
: _This is an accumulating counter._
host
: As set in the server config, this should be the full DNS resolveable name or FQDN for the host on which this
Icecast instance is running.
listener_connections
: Number of listener connections to mount points.
_This is an accumulating counter._
listeners
: Number of currently active listener connections.
location
: As set in the server config, this is a free form field that should describe e.g. the physical location of this server.
server_id
: Defaults to the version string of the currently running Icecast server. While not recommended it can be overriden in
the server config.
server_start_iso8601
: Timestamp of server startup in ISO 8601 date format.
server_start
: Timestamp of server startup in RFC 2822 date format. This field is deprecated and may be removed in a future version,
please use `server_start_iso8601` instead.
source_client_connections
: Source client connections are the number of times (cumulative since start-up, not just currently connected) a source
client has connected to Icecast.
_This is an accumulating counter._
source_relay_connections
: Number of outbound relay connections to (master) icecast servers.
_This is an accumulating counter._
source_total_connections
: Both clients and relays.
_This is an accumulating counter._
sources
: The total of currently connected sources.
stats
: The total of currently connected STATS clients.
stats_connections
: Number of times a stats client has connected to Icecast.
_This is an accumulating counter._
## Source-specific Statistics
Please note that the statistics are valid within the scope of the current source connection.
A reconnect or disconnection will reset those.
artist
: Artist of the current song
_Metadata set by source client_
title
: Title of the current song
_Metadata set by source client_
audio_bitrate
: Audio bitrate in bits/s
_Can be set by source client_
audio_channels
: Number of audio channels.
audio-info
: Information about the bitrate/samplerate/quality of the stream.
Also used for directory listings.
_Metadata set by source client_
Example:
`samplerate=44100;quality=10%2e0;channels=2` (LadioCast)
`ice-bitrate=128;ice-channels=2;ice-samplerate=44100` (Butt)
ice-bitrate
: Information about the audio bitrate (in kbit/s) of the stream.
_Can be set by source client_
samplerate
: Information about the samplerate of the stream.
_Can be set by source client_
quality
: Information about the audio quality of the stream.
_Metadata set by source client_
frame_rate
: Information about the framerate of the stream.
_Only present for video streams_
frame_size
: Information about the frame size of the stream.
_Only present for video streams_
video_bitrate
: Information about the video bitrate of the stream.
_Only present for video streams_
video_quality
: Information about the video quality of the stream.
_Only present for video streams_
server_name
: Stream name
_Metadata set by source client_
server_description
: Stream description
_Metadata set by source client_
server_type
: MIME-type for the stream currently active on this mountpoint.
subtype
: MIME-subtype, can be e.g. codecs like Opus, Vorbis, Theora.
Separated with `/`.
listener_peak
: Peak concurrent number of listener connections for this mountpoint.
listeners
: The number of currently connected listeners.
listenurl
: URL to this mountpoint. (This is not aware of aliases)
max_listeners
: Maximum number of listeners permitted to concurrently connect to this mountpoint.
public
: Flag that indicates whether this mount is to be listed on a directory.
_Set by source client, can be overriden by server config_
slow_listeners
: Number of slow listeners
source_ip
: IP address of the currently connected source client.
In case of relays the content of `<server>`.
stream_start_iso8601
: Timestamp of when the currently active source client connected to this mount point in ISO 8601 date format.
stream_start
: Timestamp of when the currently active source client connected to this mount point in RFC 2822 date format.
This field is deprecated and may be removed in a future version, please use `stream_start_iso8601` instead.
total_bytes_read
: Total number of bytes received from the source client.
total_bytes_sent
: Total number of bytes sent to all listener connections since last source connect.
user_agent
: HTTP user agent string as sent by the source client.
Additional data can be accessed through the admin interface, as every page of the admin
interface has an XML equivalent.

11
doc/docs/win32.md Normal file
View File

@ -0,0 +1,11 @@
The Win32 port of Icecast 2 is a simple command line application,
it used to be a UI framework around the core Icecast 2 server.
The GUI is no longer necessary as Icecast has achieved all of its
functionality in its web interface.
Most of the features of Icecast 2 are available in the Win32 port.
__A notable absence is IPv6 support.__
We are planning to reintroduce the capability to start Icecast
as a Windows Service in the 2.5.0 release.

95
doc/docs/yp.md Normal file
View File

@ -0,0 +1,95 @@
# Overview
A YP directory is a listing of broadcast streams. The Icecast project has it own directory located at
[http://dir.xiph.org](http://dir.xiph.org).
The Icecast configuration file contains entries for all the currently enabled directory servers. Listing your stream in a directory is
a combination of settings in the Icecast configuration file and also in your source client. It is of great importance
to configure Icecast correctly, as even one wrong setting can prevent listings to be accepted by a directory.
# Configuring Icecast for Directory Support
First of all, Icecast must have been built with directory support. This is automatically done if you have libcurl installed.
If libcurl is not detected when icecast is compiled, then directory support is disabled and listing attempts will fail.
If Icecast has been built with directory support, then the following configuration options control the directory settings:
```xml
<directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://dir.xiph.org/cgi-bin/yp-cgi</yp-url>
</directory>
```
Multiple directory XML chunks can be specified in order to be listed in multiple directories.
In the default configuration the directory settings are commented out by being enclosed in `<!--` and `-->`.
By removing these comment markers and restarting/reloading Icecast the entry becomes active.
## Further options that play a significant role in directory listings
hostname
: The hostname option **MUST** be set to a name that resolves to the machine this Icecast server runs on
(IP address is also permissible, but proper domain name is preferred).
listener-socket port
: The **first** `listener-socket`+`port` entry in the configuration is used to build the URL advertized to the directory server.
listener-socket bind-address
: If you don't specify an explicit `bind-address`, including `::` and `0.0.0.0`, then the default
bind behaviour of your operating system will apply, this may have unexpected consequences for dual-stack
(IPv6 and IPv4) setups. Icecast may end up only listening on IPv4.
If your hostname resolves to both an AAAA and an A record (IPv6 and IPv4), then you **MUST** verify,
that Icecast listens to both. If in doubt create two listener-socket entries and use `::` and `0.0.0.0`
as the respective `bind-address`.
admin
: If you are listing on a directory, then this field **MUST** contain a valid email address of a technical contact
on your side. Directory admins will use this to reach you in case your server is misconfigured and causes problems
for listeners and the directory. An invalid or unreachable address is likely to get your radio/server/network banned from the directory.
### Verifying the advertized URL
After adjusting the settings and configuring your source client, you should verify your setup:
Go to the Icecast web interface, specifically the admin part `/admin/` and look for the `listenurl` values
of your streams. These URLs **MUST** work from the public internet, or your listings will fail.
This is also one of the checks performed by a directory server. Common misconfigurations are:
* `<hostname>` set to `localhost` instead of correct domain name
* `<hostname>` set to some address that does **NOT** point to the Icecast server, but e.g. a homepage
* hostname has AAAA record but Icecast not bound to IPv6
* multiple `<listener-socket>` entries, but the first one is not publicly reachable
# Configuring Your Source Client for Directory Listings
This is usually covered in the source client documentation. More specifically, the source client needs to provide
the HTTP header `Ice-Public: 1` on connect in order to enable directory listing of the stream.
This can however be overridden in the server side mount point settings, refer to “[Icecast Config File](config-file.html#mountsettings)”
for further details.
If a mountpoint is being listed on a directory, then you will see some additional statistics relating to the directory such as
`last-touch`, `currently-playing`, etc.
# Troubleshooting
As with all Icecast problems, the error log is the goto place to start. If necessary temporary increase the log level to
`4` (debug) and reload the Icecast config. All relevant messages will contain `YP`. Especially those messages that tell
you that something `failed` will contain important hints and or messages from the directory server. If your entry submission
is directly rejected the server will tell why, if your entry gets delisted after submission, then you will see
updates/touches fail. Depending on the directory server the stream reachability check will be deferred, so you will see
a successfull initial submission, but if your stream is found to be unreachable it will be delisted and updates will fail.
Please note that directories will check both IPv6 and IPv4 availability of streams. See the list of common misconfigurations
for further hints.
Should you still have problems listing on [http://dir.xiph.org](dir.xiph.org), then please:
* Set your logging to `4` (debug)
* Reload/restart Icecast
* Go through the common misconfigurations
* Make sure your streams are running and marked public (either by source setting or mountpoint override)
* Wait for **one hour**
* Filter the error log for messages, from the last hour, that are beginning with `yp/`
* Join the [http://lists.xiph.org/mailman/listinfo/icecast](Icecast users mailing list) (else the following step will fail!)
* Send a mail to [mailto:icecast@xiph.org](icecast@xiph.org) containing:
1. The public URL of your Icecast server - e.g. `http://icecast.example.org:8000/` (Even if you have removed the status pages! This does **NOT** mean your homepage.)
2. The `<hostname>`, `<listen-socket>` and `<directory>` sections of your `icecast.xml`
4. Your Icecast version and operating system / distribution
3. The *filtered* error.log prepared previously (as an attachment)
* Wait for replies from the mailing list

56
doc/faq.html
View File

@ -1,56 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; FAQ</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; FAQ</h2>
<div class="article">
<h3 id="general-questions">General Questions</h3>
<h4 id="what-is-icecastorg">What is Icecast.org?</h4>
<p>Icecast.org, the project, is a collection of programs and libraries for streaming audio over the Internet. This includes:
* Icecast, a program that streams audio data to listeners
* libshout, a library for communicating with Icecast servers
* IceS, a program that sends audio data to Icecast servers</p>
<p>A source client is an external program which is responsible for sending content data to Icecast. Some source clients that
support Icecast 2 are Oddcast, Ices 2, Ices 0.3, and DarkIce.</p>
<h4 id="what-is-icecast-the-program">What is Icecast, the program?</h4>
<p>Icecast streams audio to listeners, and is compatible with Nullsoft’s Shoutcast.</p>
<h4 id="what-is-libshout">What is libshout?</h4>
<p>libshout is a library for communicating with and sending data to an Icecast server. It handles the socket connection,
the timing of the data, and prevents bad data from getting to the Icecast server.</p>
<h4 id="what-is-ices">What is Ices?</h4>
<p>Ices is a program (source client) that sends audio data to an Icecast server to broadcast to clients.<br />
Ices can either read audio data from disk, such as from Ogg Vorbis files, or sample live audio from a sound card and encode
it on the fly.</p>
<h4 id="what-can-i-use-to-listen-to-an-icecast-stream">What can I use to listen to an Icecast stream?</h4>
<p>We maintain a list of Icecast-compatible audio players at <a href="http://www.icecast.org/">icecast.org</a>.</p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

51
doc/glossary.html
View File

@ -1,51 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Glossary</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Glossary</h2>
<div class="article">
<dl>
<dt>Source client</dt>
<dd>A source client is an external program which is responsible for sending content data to Icecast.<br />
Some source clients that support Icecast 2 are Oddcast, Ices 2, Ices 0.3 and DarkIce.</dd>
<dt>Slave server (Relay)</dt>
<dd>The slave server in a relay configuration is the server that is pulling the data from the master server.
It acts as a listening client to the master server.</dd>
<dt>Master server (Relay)</dt>
<dd>The master server in a relay configuration is the server that has the stream that is being relayed.</dd>
<dt>Mountpoint</dt>
<dd>A mountpoint is a resource on the Icecast server that represents a single broadcast stream. Mountpoints are
named similar to files (<code>/mystream.ogg</code>, <code>/mymp3stream</code>).<br />
When listeners connect to Icecast, they must specify the mountpoint in the request (i.e. <code>http://192.168.1.10:8000/mystream.ogg</code>).
Additionally, source clients must specify a mountpoint when they connect as well. Statistics are kept track of by mountpoint.
Mountpoints are a fundamental aspect of Icecast 2 and how it is organized.</dd>
<dt>Fallback mountpoint</dt>
<dd>A fallback mountpoint is configured with a parent mountpoint. In the event of the parent mountpoint losing connection with Icecast,
Icecast will then move all clients currently connected to the now defunct mountpoint to it’s fallback mountpoint.</dd>
</dl>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

8
doc/img/Makefile.am
View File

@ -1,8 +0,0 @@
## Process this file with automake to produce Makefile.in
AUTOMAKE_OPTIONS = foreign
otherdocdir = $(docdir)/img
otherdoc_DATA = listener_auth1.png listener_auth2.png listener_auth3.png masterslave.png relay.png
EXTRA_DIST = $(otherdoc_DATA)

BIN
doc/img/listener_auth1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 202 KiB

BIN
doc/img/listener_auth2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 118 KiB

BIN
doc/img/listener_auth3.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 98 KiB

BIN
doc/img/masterslave.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 9.1 KiB

BIN
doc/img/relay.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 9.7 KiB

99
doc/index.html
View File

@ -1,99 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Table of Contents</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Table of Contents</h2>
<div class="article">
<h3 id="pages">Pages</h3>
<ul>
<li><a href="changes.html">Changes</a></li>
<li><a href="introduction.html">Introduction</a></li>
<li><a href="basic-setup.html">Basic Setup</a></li>
<li><a href="config-file.html">Icecast Config File</a></li>
<li><a href="admin-interface.html">Admin Interface</a></li>
<li><a href="server-stats.html">Server Statistics</a></li>
<li><a href="relaying.html">Relaying</a></li>
<li><a href="yp.html">Listing in a YP directory</a></li>
<li><a href="auth.html">Authentication</a></li>
<li><a href="win32.html">Win32 specific documentation</a></li>
<li><a href="glossary.html">Glossary</a></li>
<li><a href="faq.html">FAQ</a></li>
</ul>
</div>
<div class="article">
<h3 id="icecast-241-readme">Icecast 2.4.99.1 Readme</h3>
<p>Icecast is a streaming media server which currently supports Ogg
Vorbis and MP3 audio streams. It can be used to create an Internet
radio station or a privately running jukebox and many things in
between. It is very versatile in that new formats can be added
relatively easily and supports open standards for commuincation and
interaction. </p>
<p>Icecast is distributed under the GNU GPL, version 2. A copy of this
license is included with this software in the COPYING file.</p>
</div>
<div class="article">
<h3 id="prerequisites">Prerequisites</h3>
<p>Icecast requires the following packages:</p>
<ul>
<li><a href="http://xmlsoft.org/downloads.html">libxml2</a></li>
<li><a href="http://xmlsoft.org/XSLT/downloads.html">libxslt</a></li>
<li><a href="http://curl.haxx.se/download.html">curl</a> (&gt;= version 7.10 required)</li>
<li><a href="http://www.vorbis.com/files">ogg/vorbis</a> (&gt;= version 1.0 required)</li>
<li>openssl (optional, enable if SSL support is desired)</li>
</ul>
</div>
<div class="article">
<h3 id="buildinstall">Build/Install</h3>
<p>To build icecast on a Unix platform, perform the following:</p>
<p>Run</p>
<pre><code>./configure
make
make install
</code></pre>
<p>to build and install this release.</p>
<p>A sample config file will be placed in <code>/usr/local/etc</code> (on UNIX) or in
the current working directory (on Win32) and is called <code>icecast.xml</code></p>
<p>Documentation for Icecast is available in the doc directory, by
viewing <code>doc/index.html</code> in a browser.</p>
<p>Please email us at icecast@xiph.org, or come and see us
at irc.freenode.net, channel #icecast, if you have any troubles.</p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

73
doc/introduction.html
View File

@ -1,73 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Introduction</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Introduction</h2>
<div class="article">
<h3 id="what-is-icecast">What is Icecast?</h3>
<p>Icecast is a streaming media server which currently supports Ogg Vorbis, Opus, Theora and WebM streams, MP3 and AAC streams are known to work. It can be used to create an Internet radio station or a privately running jukebox and many things in between. It is very versatile in that new formats can be added relatively easily and supports open standards for commuincation and interaction.</p>
<p>There are two major parts to most streaming media servers: the component providing the content (what we call source clients) and the component which is responsible for serving that content to listeners (this is the function of icecast).</p>
</div>
<div class="article">
<h3 id="what-platforms-are-supported">What platforms are supported?</h3>
<p>Currently the following Unix platforms are supported:</p>
<ul>
<li>Linux (Most flavors including Redhat and Debian)</li>
<li>FreeBSD</li>
<li>OpenBSD</li>
<li>Solaris</li>
</ul>
<p>Currently the following Windows platforms are supported:</p>
<ul>
<li>Windows Vista</li>
<li>Windows 7</li>
<li>Windows 8</li>
<li>Windows Server 2003</li>
<li>Windows Server 2008</li>
<li>Windows Server 2012</li>
</ul>
</div>
<div class="article">
<h3 id="where-do-i-go-for-questions">Where do I go for questions?</h3>
<p>There are many ways to contact the icecast development team</p>
<p>Best Ways:</p>
<ul>
<li>Icecast mailing list <a href="http://lists.xiph.org/mailman/listinfo/icecast">http://lists.xiph.org/mailman/listinfo/icecast</a></li>
<li>Icecast Developers mailing list <a href="http://lists.xiph.org/mailman/listinfo/icecast-dev">http://lists.xiph.org/mailman/listinfo/icecast-dev</a></li>
<li>Icecast IRC chat room - irc.freenode.net : #icecast</li>
</ul>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

15
doc/mkdocs.yml.in Normal file
View File

@ -0,0 +1,15 @@
site_name: @PACKAGE_NAME@ Docs
theme: readthedocs
pages:
- [index.md, Introduction]
- [basic_setup.md, Basic Setup]
- [config_file.md, Configuration File]
- [server_stats.md, Server Statistics]
- [auth.md, Authentication]
- [relaying.md, Relaying]
- [yp.md, Listing in a YellowPage Directory]
- [admin_interface.md, Admin Interface]
- [win32.md, Windows Specific]
markdown_extensions: [def_list, admonition]

95
doc/relaying.html
View File

@ -1,95 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Relaying</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Relaying</h2>
<div class="article">
<h3 id="overview">Overview</h3>
<p>Relaying is the process by which one server mirrors one or more streams from a remote server. The servers
need not be of the same type (i.e. Icecast can relay from Shoutcast). Relaying is used primarily for large
broadcasts that need to distribute listening clients across multiple physical machines.</p>
</div>
<div class="article">
<h3 id="type-of-relays">Type of Relays</h3>
<p>There are two types of relays that icecast supports.<br />
The first type is when both master and slave servers are Icecast 2 servers. In this case, a “master-slave” relay
can be setup such that all that needs to be done is configure the slave server with the connection information
(server IP and port) of the master server and the slave will mirror all mountpoints on the master server. The slave
will also periodically check the master server to see if any new mountpoints have attached and if so will relay those
as well. </p>
<p>The second type of relay is a “single-broadcast” relay. In this case, the slave server is configured with a
server IP, port and mount and only the mountpoint specified is relayed. In order to relay a broadcast stream on
a Shoutcast server, you must use the “single-broadcast” relay and specify a mountpoint of <code>/</code>.</p>
</div>
<div class="article">
<h3 id="setting-up-a-master-slave-relay">Setting Up a Master-Slave Relay</h3>
<p>In order to setup a relay of this type both servers (the one you wish to relay and the one doing the relaying)
need to be Icecast 2 servers. The following configuration snippet is used as an example:</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;master-server&gt;</span>192.168.1.11<span class="nt">&lt;/master-server&gt;</span>
<span class="nt">&lt;master-server-port&gt;</span>8001<span class="nt">&lt;/master-server-port&gt;</span>
<span class="nt">&lt;master-update-interval&gt;</span>120<span class="nt">&lt;/master-update-interval&gt;</span>
<span class="nt">&lt;master-password&gt;</span>hackme<span class="nt">&lt;/master-password&gt;</span></code></pre></div>
<p>In this example, this configuration is setup in the server which will be doing the relaying (slave server).
The master server in this case need not be configured (and actually is unaware of the relaying being performed)
as a relay. When the slave server is started, it will connect to the master server located at 192.168.1.11:8001
and will begin to relay all mountpoints connected to the master server. Additionally, every master-update-interval
(120 seconds in this case) the slave server will poll the master server to see if any new mountpoints have connected,
and if so, the slave server will relay those as well. Note that the names of the mountpoints on the slave server will
be identical to those on the master server. </p>
</div>
<div class="article">
<h3 id="setting-up-a-single-broadcast-relay">Setting Up a Single-Broadcast Relay</h3>
<p>In this case, the master server need not be an Icecast 2 server. Supported master servers for a single-broadcast
relay are Shoutcast, Icecast 1.x, and of course Icecast 2. The following configuration snippet is used as an example:</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;relay&gt;</span>
<span class="nt">&lt;server&gt;</span>192.168.1.11<span class="nt">&lt;/server&gt;</span>
<span class="nt">&lt;port&gt;</span>8001<span class="nt">&lt;/port&gt;</span>
<span class="nt">&lt;mount&gt;</span>/example.ogg<span class="nt">&lt;/mount&gt;</span>
<span class="nt">&lt;local-mount&gt;</span>/different.ogg<span class="nt">&lt;/local-mount&gt;</span>
<span class="nt">&lt;relay-shoutcast-metadata&gt;</span>0<span class="nt">&lt;/relay-shoutcast-metadata&gt;</span>
<span class="nt">&lt;/relay&gt;</span></code></pre></div>
<p>In this example, this configuration is also setup in the server which will be doing the relaying (slave server).
The master server in this case need not be configured (and actually is unaware of the relaying being performed) as a
relay. When the slave server is started, it will connect to the master server located at 192.168.1.11:8001 and will
begin to relay only the mountpoint specified (<code>/example.ogg</code> in this case). Using this type of relay, the user can
override the local mountpoint name and make it something entirely different than the one on the master server.
Additionally, if the server is a Shoutcast server, then the <code>&lt;mount&gt;</code> must be specified as <code>/</code>.<br />
And if you want the Shoutcast relay stream to have metadata contained within it (Shoutcast metadata is embedded
in the stream itself) then the <code>&lt;relay-shoutcast-metadata&gt;</code> needs to be set to <code>1</code>.</p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

289
doc/server-stats.html
View File

@ -1,289 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Server Statistics</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Server Statistics</h2>
<div class="article">
<h3 id="overview">Overview</h3>
<p>Icecast provides extensive run time statistics. Both in the form of active connection numbers and cumulative
counters (since server startup or respectively source connection startup).</p>
</div>
<div class="article">
<h3 id="xslt">HTML interface, XSLT generated</h3>
<p>Icecast comes with a basic, XHTML web interface. It exposes a basic set of server statistics that should
fulfil basic user needs. If so desired the files in web-root can be customized to contain more or less
information (see section on raw XML data below).<br />
<strong>We strongly discourage attempts to scrape data from the web interface</strong> as we do not consider this an
API and will change it, even completely, between versions!<br />
<strong>The preferred ways are custom XSLT, JSON and raw XML.</strong></p>
</div>
<!-- FIXME -->
<div class="article">
<h3 id="json">JSON API, machine readable data</h3>
<p>Since version 2.4.0 Icecast includes a basic JSON API (<code>/status-json.xsl</code>) based on a xml2json template by Doeke Zanstra
(see <code>xml2json.xslt</code>). It exposes the same set of server statistics that are available through the web interface and
should fulfil basic user needs. The intention is to not break backwards compatibility of this interface in the future,
still we recommend to design robust software that can deal with possible changes like addition or removal of variables.
Also note that not all variables are available all the time and availability may change at runtime due to stream type, etc.</p>
</div>
<div class="article">
<h3 id="xslt_advanced">Advanced machine readable data, XSLT generated</h3>
<p>Icecast uses the very powerful libXSLT engine to transform its internal raw statistical data into custom tailored interfaces.
Many people have written custom XSLT code that produces e.g. plain text “now playing”, XSPF, VCLT, munin interface data, etc. </p>
</div>
<div class="article">
<h3 id="available_raw_data">Available raw data</h3>
<p>This section contains information about the raw XML server statistics data available inside Icecast. An example
stats XML tree will be shown and each element will be described. The following example stats tree will be used: </p>
<!-- FIXME -->
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;icestats&gt;</span>
<span class="nt">&lt;admin&gt;</span>icemaster@localhost<span class="nt">&lt;/admin&gt;</span>
<span class="nt">&lt;client_connections&gt;</span>649<span class="nt">&lt;/client_connections&gt;</span>
<span class="nt">&lt;clients&gt;</span>2<span class="nt">&lt;/clients&gt;</span>
<span class="nt">&lt;connections&gt;</span>907<span class="nt">&lt;/connections&gt;</span>
<span class="nt">&lt;file_connections&gt;</span>379<span class="nt">&lt;/file_connections&gt;</span>
<span class="nt">&lt;host&gt;</span>localhost<span class="nt">&lt;/host&gt;</span>
<span class="nt">&lt;listener_connections&gt;</span>90<span class="nt">&lt;/listener_connections&gt;</span>
<span class="nt">&lt;listeners&gt;</span>0<span class="nt">&lt;/listeners&gt;</span>
<span class="nt">&lt;location&gt;</span>Earth<span class="nt">&lt;/location&gt;</span>
<span class="nt">&lt;server_id&gt;</span>Icecast 2.5<span class="nt">&lt;/server_id&gt;</span>
<span class="nt">&lt;source_client_connections&gt;</span>164<span class="nt">&lt;/source_client_connections&gt;</span>
<span class="nt">&lt;source_relay_connections&gt;</span>0<span class="nt">&lt;/source_relay_connections&gt;</span>
<span class="nt">&lt;source_total_connections&gt;</span>164<span class="nt">&lt;/source_total_connections&gt;</span>
<span class="nt">&lt;sources&gt;</span>2<span class="nt">&lt;/sources&gt;</span>
<span class="nt">&lt;stats&gt;</span>0<span class="nt">&lt;/stats&gt;</span>
<span class="nt">&lt;stats_connections&gt;</span>0<span class="nt">&lt;/stats_connections&gt;</span>
<span class="nt">&lt;source</span> <span class="na">mount=</span><span class="s">&quot;/audio.ogg&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;title&gt;</span>All that she wants<span class="nt">&lt;/title&gt;</span>
<span class="nt">&lt;artist&gt;</span>Ace of Base<span class="nt">&lt;/artist&gt;</span>
<span class="nt">&lt;audio_bitrate&gt;</span>499821<span class="nt">&lt;/audio_bitrate&gt;</span>
<span class="nt">&lt;audio_channels&gt;</span>2<span class="nt">&lt;/audio_channels&gt;</span>
<span class="nt">&lt;audio_info&gt;</span>samplerate=44100;quality=10%2e0;channels=2<span class="nt">&lt;/audio_info&gt;</span>
<span class="nt">&lt;audio_samplerate&gt;</span>44100<span class="nt">&lt;/audio_samplerate&gt;</span>
<span class="nt">&lt;channels&gt;</span>2<span class="nt">&lt;/channels&gt;</span>
<span class="nt">&lt;genre&gt;</span>various<span class="nt">&lt;/genre&gt;</span>
<span class="nt">&lt;ice-bitrate&gt;</span>499<span class="nt">&lt;/ice-bitrate&gt;</span>
<span class="nt">&lt;listener_peak&gt;</span>0<span class="nt">&lt;/listener_peak&gt;</span>
<span class="nt">&lt;listeners&gt;</span>0<span class="nt">&lt;/listeners&gt;</span>
<span class="nt">&lt;listenurl&gt;</span>http://localhost:8000/audio<span class="nt">&lt;/listenurl&gt;</span>
<span class="nt">&lt;max_listeners&gt;</span>unlimited<span class="nt">&lt;/max_listeners&gt;</span>
<span class="nt">&lt;public&gt;</span>1<span class="nt">&lt;/public&gt;</span>
<span class="nt">&lt;quality&gt;</span>10.0<span class="nt">&lt;/quality&gt;</span>
<span class="nt">&lt;samplerate&gt;</span>44100<span class="nt">&lt;/samplerate&gt;</span>
<span class="nt">&lt;server_description&gt;</span>Teststream<span class="nt">&lt;/server_description&gt;</span>
<span class="nt">&lt;server_name&gt;</span>Great audio stream<span class="nt">&lt;/server_name&gt;</span>
<span class="nt">&lt;server_type&gt;</span>application/ogg<span class="nt">&lt;/server_type&gt;</span>
<span class="nt">&lt;server_url&gt;</span>http://example.org/<span class="nt">&lt;/server_url&gt;</span>
<span class="nt">&lt;slow_listeners&gt;</span>0<span class="nt">&lt;/slow_listeners&gt;</span>
<span class="nt">&lt;source_ip&gt;</span>192.0.2.21<span class="nt">&lt;/source_ip&gt;</span>
<span class="nt">&lt;subtype&gt;</span>Vorbis<span class="nt">&lt;/subtype&gt;</span>
<span class="nt">&lt;total_bytes_read&gt;</span>3372153<span class="nt">&lt;/total_bytes_read&gt;</span>
<span class="nt">&lt;total_bytes_sent&gt;</span>0<span class="nt">&lt;/total_bytes_sent&gt;</span>
<span class="nt">&lt;user_agent&gt;</span>LadioCast/0.10.5 libshout/2.3.1<span class="nt">&lt;/user_agent&gt;</span>
<span class="nt">&lt;/source&gt;</span>
<span class="nt">&lt;source</span> <span class="na">mount=</span><span class="s">&quot;/video.ogg&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;audio_bitrate&gt;</span>276000<span class="nt">&lt;/audio_bitrate&gt;</span>
<span class="nt">&lt;audio_channels&gt;</span>6<span class="nt">&lt;/audio_channels&gt;</span>
<span class="nt">&lt;audio_samplerate&gt;</span>48000<span class="nt">&lt;/audio_samplerate&gt;</span>
<span class="nt">&lt;frame_rate&gt;</span>25.00<span class="nt">&lt;/frame_rate&gt;</span>
<span class="nt">&lt;frame_size&gt;</span>720 x 576<span class="nt">&lt;/frame_size&gt;</span>
<span class="nt">&lt;genre&gt;</span>various<span class="nt">&lt;/genre&gt;</span>
<span class="nt">&lt;ice-bitrate&gt;</span>276<span class="nt">&lt;/ice-bitrate&gt;</span>
<span class="nt">&lt;listener_peak&gt;</span>0<span class="nt">&lt;/listener_peak&gt;</span>
<span class="nt">&lt;listeners&gt;</span>0<span class="nt">&lt;/listeners&gt;</span>
<span class="nt">&lt;listenurl&gt;</span>http://localhost:8000/video<span class="nt">&lt;/listenurl&gt;</span>
<span class="nt">&lt;max_listeners&gt;</span>unlimited<span class="nt">&lt;/max_listeners&gt;</span>
<span class="nt">&lt;public&gt;</span>0<span class="nt">&lt;/public&gt;</span>
<span class="nt">&lt;server_description&gt;</span>Unspecified description<span class="nt">&lt;/server_description&gt;</span>
<span class="nt">&lt;server_name&gt;</span>Unspecified name<span class="nt">&lt;/server_name&gt;</span>
<span class="nt">&lt;server_type&gt;</span>video/ogg<span class="nt">&lt;/server_type&gt;</span>
<span class="nt">&lt;slow_listeners&gt;</span>0<span class="nt">&lt;/slow_listeners&gt;</span>
<span class="nt">&lt;source_ip&gt;</span>192.0.2.21<span class="nt">&lt;/source_ip&gt;</span>
<span class="nt">&lt;subtype&gt;</span>Vorbis/Theora<span class="nt">&lt;/subtype&gt;</span>
<span class="nt">&lt;title&gt;</span>ERAGON<span class="nt">&lt;/title&gt;</span>
<span class="nt">&lt;total_bytes_read&gt;</span>37136<span class="nt">&lt;/total_bytes_read&gt;</span>
<span class="nt">&lt;total_bytes_sent&gt;</span>0<span class="nt">&lt;/total_bytes_sent&gt;</span>
<span class="nt">&lt;user_agent&gt;</span>Lavf/55.20.0<span class="nt">&lt;/user_agent&gt;</span>
<span class="nt">&lt;video_bitrate&gt;</span>200000<span class="nt">&lt;/video_bitrate&gt;</span>
<span class="nt">&lt;video_quality&gt;</span>0<span class="nt">&lt;/video_quality&gt;</span>
<span class="nt">&lt;/source&gt;</span>
<span class="nt">&lt;/icestats&gt;</span></code></pre></div>
<h4 id="general-statistics">General Statistics</h4>
<dl>
<dt>admin</dt>
<dd>As set in the server config, 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.</dd>
<dt>client_connections</dt>
<dd>Client connections are basically anything that is not a source connection. These include listeners (not concurrent,
but cumulative), any admin function accesses, and any static content (file serving) accesses.<br />
<em>This is an accumulating counter.</em></dd>
<dt>clients</dt>
<dd>Number of currently active client connections.</dd>
<dt>connections</dt>
<dd>The total of all inbound TCP connections since start-up.<br />
<em>This is an accumulating counter.</em></dd>
<dt>file_connections</dt>
<dd><em>This is an accumulating counter.</em></dd>
<dt>host</dt>
<dd>As set in the server config, this should be the full DNS resolveable name or FQDN for the host on which this
Icecast instance is running.</dd>
<dt>listener_connections</dt>
<dd>Number of listener connections to mount points.<br />
<em>This is an accumulating counter.</em></dd>
<dt>listeners</dt>
<dd>Number of currently active listener connections.</dd>
<dt>location</dt>
<dd>As set in the server config, this is a free form field that should describe e.g. the physical location of this server.</dd>
<dt>server_id</dt>
<dd>Defaults to the version string of the currently running Icecast server. While not recommended it can be overriden in
the server config.</dd>
<dt>server_start_iso8601</dt>
<dd>Timestamp of server startup in ISO 8601 date format.</dd>
<dt>server_start</dt>
<dd>Timestamp of server startup in RFC 2822 date format. This field is deprecated and may be removed in a future version,
please use <code>server_start_iso8601</code> instead.</dd>
<dt>source_client_connections</dt>
<dd>Source client connections are the number of times (cumulative since start-up, not just currently connected) a source
client has connected to Icecast.<br />
<em>This is an accumulating counter.</em></dd>
<dt>source_relay_connections</dt>
<dd>Number of outbound relay connections to (master) icecast servers.<br />
<em>This is an accumulating counter.</em></dd>
<dt>source_total_connections</dt>
<dd>Both clients and relays.<br />
<em>This is an accumulating counter.</em></dd>
<dt>sources</dt>
<dd>The total of currently connected sources.</dd>
<dt>stats</dt>
<dd>The total of currently connected STATS clients.</dd>
<dt>stats_connections</dt>
<dd>Number of times a stats client has connected to Icecast.<br />
<em>This is an accumulating counter.</em> </dd>
</dl>
<h4 id="source-specific-statistics">Source-specific Statistics</h4>
<p>Please note that the statistics are valid within the scope of the current source connection.<br />
A reconnect or disconnection will reset those. </p>
<dl>
<dt>artist</dt>
<dd>Artist of the current song<br />
<em>Metadata set by source client</em></dd>
<dt>title</dt>
<dd>Title of the current song<br />
<em>Metadata set by source client</em></dd>
<dt>audio_bitrate</dt>
<dd>Audio bitrate in bits/s<br />
<em>Can be set by source client</em></dd>
<dt>audio_channels</dt>
<dd>Number of audio channels.</dd>
<dt>audio-info</dt>
<dd>Information about the bitrate/samplerate/quality of the stream.
Also used for YP entries.<br />
<em>Metadata set by source client</em><br />
Example:<br />
<code>samplerate=44100;quality=10%2e0;channels=2</code> (LadioCast)<br />
<code>ice-bitrate=128;ice-channels=2;ice-samplerate=44100</code> (Butt)</dd>
<dt>ice-bitrate</dt>
<dd>Information about the audio bitrate (in kbit/s) of the stream.<br />
<em>Can be set by source client</em></dd>
<dt>samplerate</dt>
<dd>Information about the samplerate of the stream.<br />
<em>Can be set by source client</em></dd>
<dt>quality</dt>
<dd>Information about the audio quality of the stream.<br />
<em>Metadata set by source client</em></dd>
<dt>frame_rate</dt>
<dd>Information about the framerate of the stream.<br />
<em>Only present for video streams</em></dd>
<dt>frame_size</dt>
<dd>Information about the frame size of the stream.<br />
<em>Only present for video streams</em></dd>
<dt>video_bitrate</dt>
<dd>Information about the video bitrate of the stream.<br />
<em>Only present for video streams</em></dd>
<dt>video_quality</dt>
<dd>Information about the video quality of the stream.<br />
<em>Only present for video streams</em></dd>
<dt>server_name</dt>
<dd>Stream name<br />
<em>Metadata set by source client</em></dd>
<dt>server_description</dt>
<dd>Stream description<br />
<em>Metadata set by source client</em></dd>
<dt>server_type</dt>
<dd>MIME-type for the stream currently active on this mountpoint.</dd>
<dt>subtype</dt>
<dd>MIME-subtype, can be e.g. codecs like Opus, Vorbis, Theora.<br />
Separated with <code>/</code>.</dd>
<dt>listener_peak</dt>
<dd>Peak concurrent number of listener connections for this mountpoint.</dd>
<dt>listeners</dt>
<dd>The number of currently connected listeners.</dd>
<dt>listenurl</dt>
<dd>URL to this mountpoint. (This is not aware of aliases)</dd>
<dt>max_listeners</dt>
<dd>Maximum number of listeners permitted to concurrently connect to this mountpoint.</dd>
<dt>public</dt>
<dd>Flag that indicates whether this mount is to be listed on a YP.<br />
<em>Set by source client, can be overriden by server config</em></dd>
<dt>slow_listeners</dt>
<dd>Number of slow listeners</dd>
<dt>source_ip</dt>
<dd>IP address of the currently connected source client.<br />
In case of relays the content of <code>&lt;server&gt;</code>.</dd>
<dt>stream_start_iso8601</dt>
<dd>Timestamp of when the currently active source client connected to this mount point in ISO 8601 date format.</dd>
<dt>stream_start</dt>
<dd>Timestamp of when the currently active source client connected to this mount point in RFC 2822 date format.
This field is deprecated and may be removed in a future version, please use <code>stream_start_iso8601</code> instead.</dd>
<dt>total_bytes_read</dt>
<dd>Total number of bytes received from the source client.</dd>
<dt>total_bytes_sent</dt>
<dd>Total number of bytes sent to all listener connections since last source connect.</dd>
<dt>user_agent</dt>
<dd>HTTP user agent string as sent by the source client.</dd>
</dl>
<p>Additional data can be accessed through the admin interface, as every page of the admin
interface has an XML equivalent. </p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

44
doc/win32.html
View File

@ -1,44 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; Win32 Specifics</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; Win32 Specifics</h2>
<div class="article">
<p>The Win32 port of Icecast 2 is a simple command line application,
it used to be a UI framework around the core Icecast 2 server. </p>
<p>The GUI is no longer necessary as Icecast has achieved all of its
functionality in its web interface.</p>
<p>Most of the features of Icecast 2 are available in the Win32 port.<br />
<strong>A notable absence is IPv6 support.</strong></p>
<p>We are planning to reintroduce the capability to start Icecast
as a Windows Service in the 2.5.0 release.</p>
</div>
</div>
<div class="footer">
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>

133
doc/yp.html
View File

@ -1,133 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Icecast Docs Docs &mdash; YP Directories</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="assets/css/style.css" media="screen, print" />
</head>
<body>
<div class="header">
<h1><a href="#" title="Home page">Icecast</a> <span>documentation</span></h1>
</div>
<div class="section">
<h2>Icecast 2.4.99.1 Docs &mdash; YP Directories</h2>
<div class="article">
<h3 id="overview">Overview</h3>
<p>A YP directory is a listing of broadcast streams. Icecast has it own YP directory located at
<a href="http://dir.xiph.org">http://dir.xiph.org</a>. Currently Icecast can only be listed in an Icecast-supported YP directory.<br />
This means that you cannot list your stream in the Shoutcast YP directory, due to their terms of service.</p>
<p>In the Icecast configuration file are all the currently available YP directory servers. Listing your stream in a YP is
a combination of settings in the Icecast configuration file and also in your source client. It is of great importance
to configure Icecast correctly, as even one wrong setting can prevent listings to be accepted by a YP directory.</p>
</div>
<div class="article">
<h3 id="configuring-icecast-for-yp-support">Configuring Icecast for YP Support</h3>
<p>First of all, Icecast must have been built with YP support. This is automatically done if you have libcurl installed.
If libcurl is not detected when icecats is compiled, then YP support is disabled.<br />
If Icecast has been built with YP support, then the following configuration options control the YP directory settings:</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;directory&gt;</span>
<span class="nt">&lt;yp-url-timeout&gt;</span>15<span class="nt">&lt;/yp-url-timeout&gt;</span>
<span class="nt">&lt;yp-url&gt;</span>http://dir.xiph.org/cgi-bin/yp-cgi<span class="nt">&lt;/yp-url&gt;</span>
<span class="nt">&lt;/directory&gt;</span></code></pre></div>
<p>Multiple directory XML chunks can be specified in order to be listed in multiple directories.</p>
<h4 id="further-options-that-play-a-significant-role-in-yp-listings">Further options that play a significant role in YP listings</h4>
<h5 id="hostname"><code>&lt;hostname&gt;</code></h5>
<p>The hostname option <strong>MUST</strong> be set to a name that resolves to the machine this Icecast server runs on.</p>
<h5 id="listener-socketport"><code>&lt;listener-socket&gt;&lt;port&gt;</code></h5>
<p>The <strong>first</strong> <code>listener-socke</code>+<code>port</code> entry is used to build the URL advertized to the YP server.</p>
<h5 id="listener-socketbind-address"><code>&lt;listener-socket&gt;&lt;bind-address&gt;</code></h5>
<p>If you don’t specify an explicit <code>bind-address</code>, including <code>::</code> and <code>0.0.0.0</code>, then the default
bind behaviour of your operating system will apply, this may have unexpected consequences for dual-stack
(IPv6 and IPv4) setups.</p>
<p>If your hostname resolves to both an AAAA and an A record (IPv6 and IPv4), then you <strong>MUST</strong> verify,
that Icecast listens to both. If in doubt create two listener-socket entries and use <code>::</code> and <code>0.0.0.0</code>
as the respective <code>bind-address</code>.</p>
<h5 id="admin-contact"><code>&lt;admin&gt;</code> contact</h5>
<p>If you are listing on a YP, then this field <strong>MUST</strong> contain a valid email address of a technical contact
on your side. YP admins will use this to reach you in case your server is misconfigured and causes problems
for the YP directory. An invalid or unreachable address is likely to get your radio/server/network banned from YP.</p>
<h5 id="verifying-the-advertized-url">Verifying the advertized URL</h5>
<p>After adjusting the settings and configuring your source client, you should verify setup: <br />
Go to the Icecast web interface, specifically the admin part <code>/admin/</code> and look for the <code>listenurl</code> values
of your streams. These URLs <strong>MUST</strong> work from the public internet, or your listings will fail.</p>
<p>This is also one of the checks performed by a YP server. Common misconfigurations are:<br />
* <code>&lt;hostname&gt;</code> set to <code>localhost</code>
* <code>&lt;hostname&gt;</code> set to some address that does <strong>NOT</strong> point to the Icecast server
* hostname has AAAA record but Icecast not bound to <code>::</code>
* multiple <code>&lt;listener-socket&gt;</code> entries, but the first one is not publicly reachable</p>
</div>
<div class="article">
<h3 id="configuring-your-source-client-for-yp-support">Configuring Your Source Client for YP Support</h3>
<p>This is usually covered in the source client documentation. More specifically, the source client needs to provide
the HTTP header <code>Ice-Public: 1</code> on connect in order to enable YP listing of the stream.<br />
This can however be overridden in the server side mount point settings, refer to “<a href="config-file.html#mountsettings">Icecast Config File</a>”
for further details.<br />
If a mountpoint is being listed on a YP, then you will see some additional statistics relating to the YP such as
<code>last-touch</code>, <code>currently-playing</code>, etc.</p>
</div>
<div class="article">
<h3 id="troubleshooting">Troubleshooting</h3>
<p>As with all Icecast problems, the error log is the goto place to start. If necessary temporary increase the log level to
<code>4</code> (debug) and reload the Icecast config. All relevant messages will contain <code>YP</code>. Especially those messages that tell
you that something <code>failed</code> will contain important hints and or messages from the YP server. If your entry submission
is directly rejected the server will tell why, if your entry gets delisted after submission, then you will see
updates/touches fail. Depending on the YP server the stream reachability check will be deferred, so you will see
a successfull initial submission, but if your stream is found to be unreachable it will be delisted and updates will fail.
Please note that YP directories will check both IPv6 and IPv4 availability of streams. See the list of common misconfigurations
for further hints.</p>
<p>Should you still have problems listing on <a href="dir.xiph.org">http://dir.xiph.org</a>, then please:
* set your logging to <code>4</code> (debug)
* reload/restart Icecast
* make sure your streams are running and marked public (either by source setting or mountpoint override)
* wait for <strong>one hour</strong>
* filter the error log for messages from the last hour, that are beginning with <code>yp/</code>
* join the <a href="Icecast users mailing list">http://lists.xiph.org/mailman/listinfo/icecast</a> (else the following step will fail!)
* send a mail to <a href="icecast@xiph.org">mailto:icecast@xiph.org</a> containing:
1. The public URL of your Icecast server - e.g. <code>http://icecast.example.org:8000/</code> (Even if you have removed the status pages! This does <strong>NOT</strong> mean your homepage.)
2. The <code>&lt;hostname&gt;</code>, <code>&lt;listen-socket&gt;</code> and <code>&lt;directory&gt;</code> sections of your <code>icecast.xml</code>
3. The <em>filtered</em> error.log prepared previously (as an attachment)
* wait for replies from the mailing list</p>
</div>
</div>
<div class="footer">
<p><a href="https://plus.google.com/100957455777699991449/about">
<img alt="Google+" title="Find uns on Google+" src="/assets/img/google-plus.svg" style="width: 20px;">
</a>
</p>
<p>&copy; 2004-2014 Xiph.Org. All rights reserved.</p>
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
</body>
</html>