diff --git a/configure.ac b/configure.ac index 450e232e..0b815fcf 100644 --- a/configure.ac +++ b/configure.ac @@ -141,6 +141,21 @@ XIPH_PATH_OPENSSL([ [ AC_MSG_NOTICE([SSL disabled!]) ]) + +dnl Documentation + +AC_PATH_PROG([MKDOCS], [mkdocs], [no]) + +AS_IF([test "$MKDOCS" = "no"], [ + AC_MSG_WARN([mkdocs not found - generating docs will be disabled]) +]) +AM_CONDITIONAL([HAVE_MKDOCS], [test ! "$MKDOCS" = "no"]) + +AM_COND_IF([HAVE_MKDOCS], [ + AC_CONFIG_FILES([doc/mkdocs.yml]) +]) + + dnl Make substitutions AC_SUBST(XIPH_CPPFLAGS) @@ -161,8 +176,6 @@ AC_SUBST(KATE_LIBS) AC_OUTPUT([Makefile conf/Makefile src/Makefile src/common/avl/Makefile src/common/httpp/Makefile src/common/thread/Makefile src/common/log/Makefile -src/common/net/Makefile src/common/timing/Makefile doc/Makefile doc/img/Makefile -doc/assets/Makefile doc/assets/css/Makefile doc/assets/font/Makefile -doc/assets/img/Makefile web/Makefile web/assets/Makefile web/assets/css/Makefile +src/common/net/Makefile src/common/timing/Makefile doc/Makefile web/Makefile web/assets/Makefile web/assets/css/Makefile web/assets/font/Makefile admin/Makefile admin/includes/Makefile win32/Makefile examples/Makefile]) diff --git a/doc/Makefile.am b/doc/Makefile.am index 3b559ed0..49d735ea 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,12 +1,46 @@ ## Process this file with automake to produce Makefile.in -AUTOMAKE_OPTIONS = foreign - -SUBDIRS = assets img +EXTRA_DIST = \ + mkdocs.yml \ + docs/img/icecast_shema.svg \ + docs/admin_interface.md \ + docs/auth.md \ + docs/basic_setup.md \ + docs/config_file.md \ + docs/index.md \ + docs/introduction.md \ + docs/relaying.md \ + docs/server_stats.md \ + docs/win32.md \ + docs/yp.md docdir = $(datadir)/doc/icecast -doc_DATA = admin-interface.html auth.html changes.html faq.html \ - introduction.html relaying.html win32.html basic-setup.html \ - config-file.html glossary.html index.html server-stats.html yp.html -EXTRA_DIST = $(doc_DATA) +# Documentation generation +if HAVE_MKDOCS + +# Directory where the docs will end up +directory = $(top_srcdir)/doc/icecast/ + +EXTRA_DIST += $(directory) + +mkdocs.stamp: + cd "$(top_srcdir)/doc" && $(MKDOCS) build -d "$(directory)" + echo STAMP > mkdocs.stamp + +CLEANFILES = mkdocs.stamp + +install-data-local: + echo FIXMEFIXMEFIXME + exit + $(INSTALL) -d "$(directory)" "$(docdir)" + +uninstall-local: + ( cd "$(directory)"; find . -type f -print0) | (cd "$(docdir)"; xargs -0 rm ) + +all-local: mkdocs.stamp + +clean-local: + rm -rf "$(directory)" + +endif diff --git a/doc/admin-interface.html b/doc/admin-interface.html deleted file mode 100644 index 0df75833..00000000 --- a/doc/admin-interface.html +++ /dev/null @@ -1,143 +0,0 @@ - - -
-This section contains information about the admin interface of icecast. Through this interface the user can manipulate many server features. From it you can gather statistics, move listeners from mountpoint to mountpoint, disconnect connected sources, disconnect connected listeners, and many other activities. Each function is enumerated here as well as an example usage of the function.
- -Each of these functions requires HTTP authentication via the appropriate username and password. For mount-specific functions, you may use either the <admin-username>
and <admin-password>
specified in the icecast config file, or the username and password specified for that mountpoint (if any). For general functions (not specific to a single mountpoint), you must use the admin username and password. It is also important to note that in all the examples 192.168.1.10 is used as the example host and 8000 is used as the example port for the icecast server.
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.
- -This function provides the ability for either a source client or any external program to update -the metadata information for a particular mountpoint.
- -Example:
-http://192.168.1.10:8000/admin/metadata?mount=/mystream&mode=updinfo&song=ACDC+Back+In+Black
This function provides the ability for either a source client or any external program to update the -“fallback mountpoint” for a particular mountpoint. Fallback mounts are those that are used in the even -of a source client disconnection. If a source client disconnects for some reason that all currently -connected clients are sent immediately to the fallback mountpoint.
- -Example:
-http://192.168.1.10:8000/admin/fallbacks?mount=/mystream.ogg&fallback=/myfallback.ogg
This function lists all the clients currently connected to a specific mountpoint. The results are sent -back in XML form.
- -Example:
-http://192.168.1.10:8000/admin/listclients?mount=/mystream.ogg
This function provides the ability to migrate currently connected listeners from one mountpoint to another. -This function requires 2 mountpoints to be passed in: mount (the from mountpoint) and destination -(the to mountpoint). After processing this function all currently connected listeners on mount will -be connected to destination. Note that the destination mountpoint must exist and have a sounce client -already feeding it a stream.
- -Example:
-http://192.168.1.10:8000/admin/moveclients?mount=/mystream.ogg&destination=/mynewstream.ogg
This function provides the ability to disconnect a specific listener of a currently connected mountpoint.
-Listeners are identified by a unique id that can be retrieved by via the “List Clients” admin function.
-This id must be passed in to the request via the variable id
. After processing this request, the listener will no longer be
-connected to the mountpoint.
Example:
-http://192.168.1.10:8000/admin/killclient?mount=/mystream.ogg&id=21
This function will provide the ability to disconnect a specific mountpoint from the server. The mountpoint
-to be disconnected is specified via the variable mount
.
Example:
-http://192.168.1.10:8000/admin/killsource?mount=/mystream.ogg
The stats function provides the ability to query the internal statistics kept by the Icecast server.
-Almost all information about the internal workings of the server such as the mountpoints connected,
-how many client requests have been served, how many listeners for each mountpoint, etc, are available
-via this admin function.
-Note that this admin function can also be invoked via the http://server:port/admin/stats.xml syntax,
-however this syntax should not be used and will eventually become deprecated!
Example:
-http://192.168.1.10:8000/admin/stats
The list mounts function provides the ability to view all the currently connected mountpoints.
- -Example:
-http://192.168.1.10:8000/admin/listmounts
As an alternative to manually invoking these URLs, a web-based admin interface was developed. This
-interface provides the same functions that were identified and described above but presents them in
-a little nicer way. The web-based admin Interface to Icecast is shipped with Icecast provided in the
-admin
directory and comes ready to use. All the user needs to do is set the path to this directory
-in the config file via the <adminroot>
config variable.
-The web-based admin interface is a series of XSLT files which are used to display all the XML obtained
-via the URL admin interface. This can be changed and modified to suit the user’s need. Knowledge of
-XSLT and transformations from XML to HTML are required in order to make changes to these scripts.
The main URL for the Web-Based Admin Interface is:
-http://192.168.1.10:8000/admin/stats.xsl
From this URL all of the other admin functions can be exercised.
-Modification of existing XSLT transforms in /admin
is allowed, but new files cannot be created here.
-Creation of new XSLT transforms as well as modification of existing transforms is allowed in /web
.
-These work using the document returned by /admin/stats.xml
.
-To see the XML document that is applied to each admin XSLT, just remove the .xsl
in your request
-(i.e. /admin/listclients
). You can then code your XSLT transform accordingly.
Listener authentication is a feature of Icecast which allows you to secure a certain mountpoint such that in order to listen, -a listener must pass some verification test. With this feature, a simple pay-for-play operation (eg. user/pass), or some filtering -based on the listener connection can be performed. This section will show you the basics of setting up and maintaining this component.
- -To define listener authentication, a group of tags are specified in the <mount>
group relating to the mountpoint. This means
-that authentication can apply to listeners of source clients or relays.
The following authentication mechanisms can apply to listeners:
- -The listener authentication within a specified mount in the icecast XML configuration can apply to either to a stream from a -source client, relay or a webroot based file. They do apply to intro files or fallback streams.
- -In order to use listener authentication, you must configure a mount specific option. This means that you have to provide
-a <mount>
section in the main icecast config file. The following is an example:
<mount>
- <mount-name>/example.ogg</mount-name>
- <authentication type="htpasswd">
- <option name="filename" value="myauth"/>
- <option name="allow_duplicate_users" value="0"/>
- </authentication>
-</mount>
To support listener authentication you must provide at a minimum <mount-name>
and <authentication>
.
-The mount-name
is the name of the mountpoint that you will use to connect your source client with and authentication
configures
-what type of Icecast authenticator to use.
-Currently, only htpasswd
and url
are implemented. Each authenticator has a variable number of options that are required and
-these are specified as shown in the example.
-The htpasswd authenticator requires a few parameters:
-The first, filename
, specifies the name of the file to use to store users and passwords. Note that this file need not exist
-(and probably will not exist when you first set it up).
-Icecast has built-in support for managing users and passwords via the web admin interface. More on this later in this section.
-The second option, allow_duplicate_users
, if set to 0
, will prevent multiple connections using the same username. Setting this
-value to 1
will enable mutltiple connections from the same username on a given mountpoint.
-Note there is no way to specify a “max connections” for a particular user.
Icecast supports a mixture of streams that require listener authentication and those that do not.
- -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:
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:
- -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.
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.
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.
- -Authenticating listeners via the URL method involves Icecast, when a listener connects, issuing requests to a web server -and checking the response headers. If a certain header is sent back then the listener connecting is allowed to continue, -if not, an error is sent back to the listener.
- -The URLs specified will invoke some web server scripts like PHP to do any work that they may choose to do. All that is
-required of the scripting language is that POST information can be handled and response headers can be sent back.
-libcurl is used for the requesting so https connections may be possible, but be aware of the extra overhead involved.
The useragent sent in each curl request will represent the Icecast server version. The response headers will depend on
-whether the listener is to be accepted. In the case of rejection, a response header
-Icecast-Auth-Message: Reason
-should also be returned for placing in the log files.
In order to use URL based listener authentication, you must configure a mount specific option. This means that you
-have to provide a <mount>
section in the main Icecast config file. The following shows the list of options available:
<mount>
- <mount-name>/example.ogg</mount-name>
- <authentication type="url">
- <option name="mount_add" value="http://auth.example.org/stream_start.php"/>
- <option name="mount_remove" value="http://auth.example.org/stream_end.php"/>
- <option name="listener_add" value="http://auth.example.org/listener_joined.php"/>
- <option name="listener_remove" value="http://auth.example.org/listener_left.php"/>
- <option name="username" value="user"/>
- <option name="password" value="pass"/>
- <option name="auth_header" value="icecast-auth-user: 1"/>
- <option name="timelimit_header" value="icecast-auth-timelimit:"/>
- <option name="headers" value="x-pragma,x-token"/>
- <option name="header_prefix" value="ClientHeader."/>
- <option name="stream_auth" value="http://auth.example.org/source.php"/>
- </authentication>
-</mount>
The options are described below in more detail, each of which is optional, but in each case, within the POST data, -the value for each setting is encoded.
- -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.
- -mount_add
<hostname>
)action=mount_add&mount=/live&server=icecast.example.org&port=8000
This URL is for informing the auth server of a stream finishing, like the start option, no listener details -are passed.
- -mount_remove
<hostname>
)action=mount_remove&mount=/live&server=icecast.example.org&port=8000
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.
listener_add
<hostname>
)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.
action=listener_add&server=icecast.example.org&port=8000&client=1&mount=/live&user=&pass=&ip=127.0.0.1&agent=My%20player
This URL is for when a listener connection closes.
- -listener_remove
<hostname>
)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
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.
stream_auth
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.
action=stream_auth&mount=/stream.ogg&ip=192.0.2.0&server=icecast.example.org&port=8000&user=source&pass=password&admin=1
icecast-auth-user: 1
HTTP 200 OK
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 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:
- -<password>
and possibly <username>
in the <mount>
sectionstream_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).
stream_auth
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.
action=stream_auth&mount=/stream.ogg&ip=192.0.2.0&server=icecast.example.org&port=8000&user=source&pass=password&admin=1
This section will describe the essential requirements in setting up a simple Internet radio station. It is by no means a complete list but should give you enough to get started. Please also note that those are generic instructions. If you installed a Linux/Unix distribution package, then it will likely come with different paths, different means of starting it, etc. In that case please also refer to the documentation of that distribution and or a distribution specific How-To.
- -There are two major components involved: the streaming server (Icecast in this case) and the source client.
-The Icecast server will be the place where all listeners of your station will connect. The source client (in general) runs on a separate machine than Icecast, but does not necessarily need to. Source clients send the content to Icecast and provide the stream data (encoded audio) that is then relayed out to listeners by Icecast.
It is important to note that not all source clients work with Icecast 2. You will need to check to make sure that Icecast 2 is supported by your chosen source client.
- -Each Icecast server can house multiple broadcasts (or mountpoints) each containing a separate stream of content. A ‘mountpoint’ is a unique name on your server identifying a particular stream - it looks like a filename, such as ‘/stream.ogg’. A listener can only listen to a single mountpoint at a time. This means you can have a single Icecast server contain either multiple broadcasts with different content, or possibly the same broadcast but with streams of different bitrates or qualities. In this case each broadcast or stream is a separate mountpoint.
- -At this point, the steps outlined here related to the Unix version or Win32 console version of Icecast. Icecast is also available in a Win32 GUI version, and the steps are similar in setup, but not quite the same.
- -The first step in the process is to find and install the Icecast2 server itself. How to do this is not contained within this documentation. After installation you should have and Icecast binary and 3 directories
- -conf
icecast.xml
) which defines all the configuration parameters for the server. admin
logs
The next step is to edit the icecast.xml
file and set the appropriate values. Most of the specified values in the samples are fine, for a basic setup the following entries should be specified, and if neccessary, changed to suite your situation:
<hostname>
- DNS name or IP address used for stream directory listings.
-<source-password>
- Will be used for the source client authentication.
-<admin-password>
- Will be used for authenticating admin features of Icecast.
-<listen-socket>
(both port and bind-address)
Once the configuration file is modified, you should be able to start the server with the following command
- -icecast -c /path/to/icecast.xml
-
-
- If no error messages are generated, then check the error.log
file for the ‘server started’ message, it will look something like :
[2003-10-31 13:04:49] INFO main/main.c Icecast 2.3.0 server started
-
-
- You may notice slight variations to the line above, the time will no doubt be different, and on some platforms the main.c
is just main, but the key thing here is that the server is started, logging is working and the version is shown.
You can also verify that it started by visiting the following URL: http://yourip:port/admin/stats.xml
. You should be prompted for a username and password. Enter the username admin
and the password you entered for <admin-password>
. If all is well, you should see an small XML tree which represents Icecast statistics (more about that later).
Now that the Icecast server is started you must now configure your source client. The information you will need for the source client is the following:
- -IP address and Port of the icecast server - both of these come from <listen-socket>
-source password - from <source-password>
Additionally, you will need to choose a mountpoint and specify this in the source client. Icecast does not need to know about each mount point (although you can configure settings for specific mountpoint - this is covered under Advanced configuration) there are, however, some points to mention regarding mountpoints. All Ogg Vorbis streams should have mountpoints that end in .ogg
(i,e. /mystream.ogg
). This is due to the lazy way most media players infer the type of stream. MP3 streams usually do not contain an extension (/mystream). Mount points also should not contain any spaces or odd characters (again due to the lazy way many of the media players are coded).
Once you have configured your source client, you should be able to connect it to the Icecast server. Verify that it is connected by hitting the stats.xml URL that was mentioned above.
- -Now that you have the source connnected, listening to the stream involves simply opening the appropriate following URL in a browser: http://yourip:port/mounpoint-you-specified
. So, for instance, if you attached your source client to an icecast server located at 192.0.2.23:8000
with a mountpoint of /mystream.ogg
, then you would open: http://192.0.2.23:8000/mystream.ogg
or http://192.0.2.23:8000/mystream.ogg.m3u
. Note that the URL with .m3u
extention will serve up a link that opens most media players. Also it is important to note that m3u need not contain only MP3 stream, it can contain streams of arbitrary content-type and is used by Icecast to serve a playlist that represents your broadcast to listening clients. Alternatively you can open up the stream URL directly within your media player (http://192.0.2.23:8000/mystream.ogg
in this case)
<auth>
in <mount type="default">
to work properly.<fileserve>
, <hostname>
, <location>
, <admin>
and <server-id>
<audio>
or <video>
use cases and accessing the JSON status API.<on-connect>
or <on-disconnect>
, as there is a small chance of stream file descriptors being mixed up with script file descriptors, if the FD numbers go above 1024. This will be further addressed in the next Icecast release.<http-headers>
as it will prevent processing of further <header>
tags.<audio>
element for supported audio streams/status-json.xsl
) based on a xml2json template by Doeke Zanstra (see xml2json.xslt
). Output is roughly limited to data also visible through status.xsl
%x
codes in <dump-file>
. Disabled for Win32stream_start_iso8601
, server_start_iso8601
to statitics. ISO8601 compliante timestamps for statistics. Should make usage in e.g. JSON much easier. Added as new variables to avoid breaking backwards compatibilityheaders
and header_prefix
to URL based listener authlistener_remove
handler, added ip=
and agent=
_parse_mount()
when type
-attribute is setstatus2.xsl
from release. It was only a broken example file anyway.This section will describe each section of the config file and is grouped into the following sections:
- - - -Please note that, especially for new Icecast users, editing the config file can be quite tricky. -It is thus recommended to make a backup of the original config file and then start by just changing all -passwords, nothing else. You can then use the source-password to bring up an initial stream and get more -comfortable with how Icecast works.
- -Should you need to customize the configuration, then make a backup of your working config file, before you -make any changes. If Icecast refuses to start it is in most cases due to a malformed config file. In such a -case running the following command should point out most XML syntax problems.
- -xmllint icecast.xml
-
-
- Also check the Icecast error.log for additional hints in case of all problems!
- -<limits>
- <clients>100</clients>
- <sources>2</sources>
- <queue-size>102400</queue-size>
- <client-timeout>30</client-timeout>
- <header-timeout>15</header-timeout>
- <source-timeout>10</source-timeout>
- <burst-on-connect>1</burst-on-connect>
- <burst-size>65536</burst-size>
-</limits>
This section contains server level settings that, in general, do not need to be changed. -Only modify this section if you know what you are doing.
- -burst-size
instead.<authentication>
- <source-password>hackme</source-password>
- <relay-user>relay</relay-user>
- <relay-password>hackme</relay-password>
- <admin-user>admin</admin-user>
- <admin-password>hackme</admin-password>
-</authentication>
This section contains all the usernames and passwords used for administration purposes or to connect sources and relays.
- - -relay
<directory>
- <yp-url-timeout>15</yp-url-timeout>
- <yp-url>http://dir.xiph.org/cgi-bin/yp-cgi</yp-url>
-</directory>
This section contains all the settings for listing a stream on any of the Icecast YP Directory servers. -Multiple occurances of this section can be specified in order to be listed on multiple directory servers.
- -<hostname>localhost</hostname>
-<location>earth</location>
-<admin>icemaster@localhost</admin>
-<fileserve>1</fileserve>
-<server-id>icecast 2.5</server-id>
<paths><webroot>
configuration setting.
-By default the setting is enabled so that requests for the static files needed by the status
-and admin pages, such as images and CSS are retrievable.icecast
followed by a version number and most will
-not care to change it however this setting will allow this. It is not recommended to use this
-setting, unless you have very good reasons and know what you are doing.The following shows how you can specify the listening settings for the server.
- -The first shows an example of a common and simple way to define a listening socket:
- -<listen-socket>
- <port>8000</port>
-</listen-socket>
Using this as a basis we can extend this with an <bind-address>
setting to limit which address Icecast
-will listen on. Most will not need to use bind-address and often get confused by using it when there is
-no need. Another possibility is to use an <ssl>
boolean setting which informs Icecast that a secured
-connection is to be used. A common use for using a secure connection would be for admin page access.
The following shows how we can extend a single listen-socket to work with Shoutcast style source clients. -There are two issues shoutcast source clients have over icecast source clients, one is the lack of mountpoint -and the second is the requirement of two ports. Both of these issues are handled by a simple addition in -the listen-socket.
- -<listen-socket>
- <port>8000</port>
- <shoutcast-mount>/live.mp3</shoutcast-mount>
-</listen-socket>
As before the port specified is allocated but this time the shoutcast-mount implicity defines a second -listening socket whose port number is always one higher than the port defined, this also informs icecast -of which mountpoint the shoutcast source client on this socket will be using. Using this approach you can -allow multiple shoutcast source clients to connect at the same time.
- -The following is just to show the longer approach to defining shoutcast compatability.
- -<shoutcast-mount>/live.nsv</shoutcast-mount>
-<!-- You may have multiple <listen-socket> elements -->
-<listen-socket>
- <port>8000</port>
-</listen-socket>
-
-<listen-socket>
- <port>8001</port>
- <shoutcast-compat>1</shoutcast-compat>
-</listen-socket>
Note that multiple listen-socket sections may be configured in order to have Icecast listen on multiple network -interfaces or multiple ports. If a bind-address is not specified for a particular listen-socket, then the socket -will be bound to all interfaces (including IPv6 if available). For most people, the bind-address option will not -be required and often confuses people.
- -/stream
but can be overridden here to use an alternative name which may include an extension that some clients
-require for certain formats.shoutcast-compat
approach as this implicitly
-defines the second listening socket and allows for specifying multiple sockets using different mountpoints for
-shoutcast source clients. The shoutcast-mount
outside of a listen-socket
group is the global setting of the
-mountpoint to use.shoutcast-compat
. This means if you define 8001
as shoutcast-compat
, then you will need to define a listen port
-of 8000
and it must not also be defined as shoutcast-compat
. See the example config file in the distribution for more info.<http-headers>
- <header name="Access-Control-Allow-Origin" value="*" />
- <header name="X-Robots-Tag" value="index, noarchive" />
- <header name="foo" value="bar" status="200" />
- <header name="Nelson" value="Ha-Ha!" status="404" />
-</http-headers>
Icecast can be configured to send custom HTTP headers. This is available as a global setting and inside mountpoints. This section explains the global settings.
- -This functionality was introduced mainly to enable the use of simplified cross-origin resource sharing. The Icecast default configuration contains the first header, as seen in the above exmple, for this reason.
- -<header>
child elements, that specify the actual headers one by one.name
is required and its value specifies the HTTP header field name.value
is required and its value specifies the HTTP header field value.status
is optional and limits sending the header to certain HTTP status codes. If not specified, the default is to return the header for every HTTP status code. This attribute is only available for global headers, at the moment.At the moment only global headers will be sent in case the HTTP status is not “200”. This is subject to change in the future.
-Avoid placing comments inside <http-headers>
as, in this release, it will prevent Icecast from parsing further <header>
tags.
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.”
A Master server relay is only supported between Icecast servers and is used to relay a number of -mountpoints from a remote Icecast server.
- -<master-server>127.0.0.1</master-server>
-<master-server-port>8001</master-server-port>
-<master-update-interval>120</master-update-interval>
-<master-username>relay</master-username>
-<master-password>hackme</master-password>
-<relays-on-demand>0</relays-on-demand>
The following diagram shows the basics of using a Master relay.
-Please note that the slave is configured with the <master-server>
, <master-server-port>
, etc… settings
-and the master is the Icecast server from which the slave will pull mountpoints and relay them. Using a
-Master server relay, all non-hidden mountpoints on the master can be
-relayed using this mechanism.
A server is configured as a Master Server relay by specifying the <master-server>
, <master-server-port>
,
-<master-update-interval>
, <master-password>
values in the config file. The server that is being relayed
-does not need any special configuration.
relay
is used.If only specific mountpoints need to be relayed, then you can configure Icecast with a “Specific Mountpoint Relay”.
- -The following diagram shows the basics of using a Specific Mountpoint relay. Note that the relaying Icecast is
-configured with the <relay>
settings and will pull the specified mountpoint(s) and relay them to the listeners.
-Using a Specific Mountpoint Relay, only those mountpoints specified will be relayed.
Specific Mountpoint Relays can be configured to relay from an Icecast 2 server, as well as Icecast 1.x and Shoutcast.
-A server is configured as a Specific Mountpoint Server relay by specifying a <relay>
XML chunk in the config file
-for each mountpoint to be relayed. The server that is being relayed does not need any special configuration.
<relay>
- <server>127.0.0.1</server>
- <port>8001</port>
- <mount>/example.ogg</mount>
- <local-mount>/different.ogg</local-mount>
- <username>joe</username>
- <password>soap</password>
- <relay-shoutcast-metadata>0</relay-shoutcast-metadata>
- <on-demand>1</on-demand>
-</relay>
/
or /name
.1
: enabled, 0
: disabled1
: enabled, 0
: disabled (default is <relays-on-demand>
). This is useful in cases where you want to
-limit bandwidth costs when no one is listening.<mount type="normal">
- <mount-name>/example-complex.ogg</mount-name>
- <username>othersource</username>
- <password>hackmemore</password>
- <max-listeners>1</max-listeners>
- <max-listener-duration>3600</max-listener-duration>
- <dump-file>/tmp/dump-example1.ogg</dump-file>
- <intro>/intro.ogg</intro>
- <fallback-mount>/example2.ogg</fallback-mount>
- <fallback-override>1</fallback-override>
- <fallback-when-full>1</fallback-when-full>
- <charset>ISO8859-1</charset>
- <public>1</public>
- <stream-name>My audio stream</stream-name>
- <stream-description>My audio description</stream-description>
- <stream-url>http://some.place.com</stream-url>
- <genre>classical</genre>
- <bitrate>64</bitrate>
- <type>application/ogg</type>
- <subtype>vorbis</subtype>
- <hidden>1</hidden>
- <burst-size>65536</burst-size>
- <mp3-metadata-interval>4096</mp3-metadata-interval>
- <authentication type="xxxxxx">
- <!-- See authentication documentation -->
- </authentication>
- <http-headers>
- <header name="Access-Control-Allow-Origin" value="*" />
- <header name="X-Robots-Tag" value="index, noarchive" />
- <header name="foo" value="bar" status="200" />
- <header name="Nelson" value="Ha-Ha!" status="404" />
- </http-headers>
- <on-connect>/home/icecast/bin/source-start</on-connect>
- <on-disconnect>/home/icecast/bin/source-end</on-disconnect>
-</mount>
This section contains the settings which apply only to a specific mountpoint and applies to an incoming -stream whether it is a relay or a source client. The purpose of the mount definition is to state certain -information that can override either global/default settings or settings provided from the incoming stream.
- -A mount does not need to be stated for each incoming source although you may want to specific certain settings -like the maximum number of listeners or a mountpoint specific username/password. As a general rule, only define -what you need to but each mount definition needs at least the mount-name. Changes to most of these will apply -across a configuration file re-read even on active streams, however some only apply when the stream starts or -ends.
- -type="normal"
mount block exists
-corresponding to your mountpoint.source
.source
.%F
.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.0
so YP advertising
-can occur however you may want to prevent it here if you intend listeners to connect to a local relay instead.<public>
charset=
parameter to the metadata update URL if they so wish.-1
indicating that it is up to the source client or relay to determine if this mountpoint
-should advertise. A setting of 0
will prevent any advertising and a setting of 1
will force it to advertise.
-If you do force advertising you may need to set other settings listed below as the YP server can refuse to advertise
-if there is not enough information provided.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.<header>
child elements, that specify the actual HTTP headers one by one.name
is required and its value specifies the HTTP header field name.value
is required and its value specifies the HTTP header field value.<paths>
- <basedir>./</basedir>
- <logdir>./logs</logdir>
- <pidfile>./icecast.pid</pidfile>
- <webroot>./web</webroot>
- <adminroot>./admin</adminroot>
- <allow-ip>/path/to/ip_allowlist</allow-ip>
- <deny-ip>/path_to_ip_denylist</deny-ip>
- <ssl-certificate>/path/to/certificate.pem</ssl-certificate>
- <ssl-allowed-ciphers>ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS</ssl-allowed-ciphers>
- <alias source="/foo" dest="/bar"/>
-</paths>
This section contains paths which are used for various things within icecast. All paths (other than any aliases) should not end in a /
.
error.log
and access.log
will be created relative to this directory./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.<alias source="/foo" dest="/bar">
<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.
<logdir>
config value.logfile.old
, or add a timestamp to the archived file (if logarchive is enabled).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.The following mapping can be used to set the appropriate value:
- -4
: Debug, Info, Warn, Error messages are printed3
: Info, Warn, Error messages are printed2
: Warn, Error messages are printed1
: Error messages only are printed<security>
- <chroot>0</chroot>
- <changeowner>
- <user>nobody</user>
- <group>nogroup</group>
- </changeowner>
-</security>
This section contains configuration settings that can be used to secure the icecast server by performing a chroot to a secured location or changing user and group on start-up. The latter allows icecast to bind to priviledged ports like 80 and 443, by being started as root and then dropping to the configured user/group after binding listener-sockets. -This is currently not supported on Win32.
- -chroot()
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.<header>
child elements, that specify the actual headers one by one.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
- -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.
- -Icecast streams audio to listeners, and is compatible with Nullsoft’s Shoutcast.
- -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.
- -Ices is a program (source client) that sends audio data to an Icecast server to broadcast to clients.
-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.
We maintain a list of Icecast-compatible audio players at icecast.org.
-/mystream.ogg
, /mymp3stream
).http://192.168.1.10:8000/mystream.ogg
).
-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.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.
- -Icecast requires the following packages:
- -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.
Please email us at icecast@xiph.org, or come and see us -at irc.freenode.net, channel #icecast, if you have any troubles.
-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).
-Currently the following Unix platforms are supported:
- -Currently the following Windows platforms are supported:
- -There are many ways to contact the icecast development team
- -Best Ways:
- -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.
- -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 “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 /
.
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:
- -<master-server>192.168.1.11</master-server>
-<master-server-port>8001</master-server-port>
-<master-update-interval>120</master-update-interval>
-<master-password>hackme</master-password>
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.
- -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:
- -<relay>
- <server>192.168.1.11</server>
- <port>8001</port>
- <mount>/example.ogg</mount>
- <local-mount>/different.ogg</local-mount>
- <relay-shoutcast-metadata>0</relay-shoutcast-metadata>
-</relay>
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 (/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) then the <relay-shoutcast-metadata>
needs to be set to 1
.
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).
- -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).
-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.
Since version 2.4.0 Icecast includes a basic JSON API (/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.
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.
-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:
- - - -<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>
server_start_iso8601
instead.Please note that the statistics are valid within the scope of the current source connection.
-A reconnect or disconnection will reset those.
samplerate=44100;quality=10%2e0;channels=2
(LadioCast)ice-bitrate=128;ice-channels=2;ice-samplerate=44100
(Butt)/
.<server>
.stream_start_iso8601
instead.Additional data can be accessed through the admin interface, as every page of the admin -interface has an XML equivalent.
- -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.
- -A YP directory is a listing of broadcast streams. Icecast has it own YP directory located at
-http://dir.xiph.org. Currently Icecast can only be listed in an Icecast-supported YP directory.
-This means that you cannot list your stream in the Shoutcast YP directory, due to their terms of service.
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.
- -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.
-If Icecast has been built with YP support, then the following configuration options control the YP directory settings:
<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.
- -<hostname>
The hostname option MUST be set to a name that resolves to the machine this Icecast server runs on.
- -<listener-socket><port>
The first listener-socke
+port
entry is used to build the URL advertized to the YP 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.
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>
contactIf you are listing on a YP, then this field MUST 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.
- -After adjusting the settings and configuring your source client, you should verify 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 YP server. Common misconfigurations are:
- * <hostname>
set to localhost
- * <hostname>
set to some address that does NOT point to the Icecast server
- * hostname has AAAA record but Icecast not bound to ::
- * multiple <listener-socket>
entries, but the first one is not publicly reachable
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 YP listing of the stream.
-This can however be overridden in the server side mount point settings, refer to “Icecast Config File”
-for further details.
-If a mountpoint is being listed on a YP, then you will see some additional statistics relating to the YP such as
-last-touch
, currently-playing
, etc.
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 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.
Should you still have problems listing on http://dir.xiph.org, then please:
-* set your logging to 4
(debug)
-* reload/restart Icecast
-* 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 (else the following step will fail!)
-* send a mail to mailto: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
- 3. The filtered error.log prepared previously (as an attachment)
-* wait for replies from the mailing list