diff --git a/configure.ac b/configure.ac index 450e232e6d5af1d5ee97394ea4507391338960d3..0b815fcfe5dffd5cd4da1acce7d41bcd905eda1e 100644 --- a/configure.ac +++ b/configure.ac @@ -141,6 +141,21 @@ XIPH_PATH_OPENSSL([ [ AC_MSG_NOTICE([SSL disabled!]) ]) + +dnl Documentation + +AC_PATH_PROG([MKDOCS], [mkdocs], [no]) + +AS_IF([test "$MKDOCS" = "no"], [ + AC_MSG_WARN([mkdocs not found - generating docs will be disabled]) +]) +AM_CONDITIONAL([HAVE_MKDOCS], [test ! "$MKDOCS" = "no"]) + +AM_COND_IF([HAVE_MKDOCS], [ + AC_CONFIG_FILES([doc/mkdocs.yml]) +]) + + dnl Make substitutions AC_SUBST(XIPH_CPPFLAGS) @@ -161,8 +176,6 @@ AC_SUBST(KATE_LIBS) AC_OUTPUT([Makefile conf/Makefile src/Makefile src/common/avl/Makefile src/common/httpp/Makefile src/common/thread/Makefile src/common/log/Makefile -src/common/net/Makefile src/common/timing/Makefile doc/Makefile doc/img/Makefile -doc/assets/Makefile doc/assets/css/Makefile doc/assets/font/Makefile -doc/assets/img/Makefile web/Makefile web/assets/Makefile web/assets/css/Makefile +src/common/net/Makefile src/common/timing/Makefile doc/Makefile web/Makefile web/assets/Makefile web/assets/css/Makefile web/assets/font/Makefile admin/Makefile admin/includes/Makefile win32/Makefile examples/Makefile]) diff --git a/doc/Makefile.am b/doc/Makefile.am index 3b559ed09d65c6c25c7ec534361f5a4f03c0e73e..49d735ea96b8f58bee7b80ac39e071121363f2b9 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,12 +1,46 @@ ## Process this file with automake to produce Makefile.in -AUTOMAKE_OPTIONS = foreign - -SUBDIRS = assets img +EXTRA_DIST = \ + mkdocs.yml \ + docs/img/icecast_shema.svg \ + docs/admin_interface.md \ + docs/auth.md \ + docs/basic_setup.md \ + docs/config_file.md \ + docs/index.md \ + docs/introduction.md \ + docs/relaying.md \ + docs/server_stats.md \ + docs/win32.md \ + docs/yp.md docdir = $(datadir)/doc/icecast -doc_DATA = admin-interface.html auth.html changes.html faq.html \ - introduction.html relaying.html win32.html basic-setup.html \ - config-file.html glossary.html index.html server-stats.html yp.html -EXTRA_DIST = $(doc_DATA) +# Documentation generation +if HAVE_MKDOCS + +# Directory where the docs will end up +directory = $(top_srcdir)/doc/icecast/ + +EXTRA_DIST += $(directory) + +mkdocs.stamp: + cd "$(top_srcdir)/doc" && $(MKDOCS) build -d "$(directory)" + echo STAMP > mkdocs.stamp + +CLEANFILES = mkdocs.stamp + +install-data-local: + echo FIXMEFIXMEFIXME + exit + $(INSTALL) -d "$(directory)" "$(docdir)" + +uninstall-local: + ( cd "$(directory)"; find . -type f -print0) | (cd "$(docdir)"; xargs -0 rm ) + +all-local: mkdocs.stamp + +clean-local: + rm -rf "$(directory)" + +endif diff --git a/doc/admin-interface.html b/doc/admin-interface.html deleted file mode 100644 index 0df7583347e73d9b3024050929cc99d8236c162d..0000000000000000000000000000000000000000 --- a/doc/admin-interface.html +++ /dev/null @@ -1,143 +0,0 @@ - - --
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-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.- -
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.- -
This function lists all the clients currently connected to a specific mountpoint. The results are sent -back in XML form.- -
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.- -
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.
This function will provide the ability to disconnect a specific mountpoint from the server. The mountpoint
-to be disconnected is specified via the variable
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!
The list mounts function provides the ability to view all the currently connected mountpoints.- -
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:
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
-These work using the document returned by
-To see the XML document that is applied to each admin XSLT, just remove the
.xsl in your request
/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
<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 is the name of the mountpoint that you will use to connect your source client with and
-what type of Icecast authenticator to use.
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:
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
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
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
-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.- -
This URL is for informing the auth server of a stream finishing, like the start option, no listener details -are passed.- -
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
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.
This URL is for when a listener connection closes.- -
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
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.
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:- -
<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).
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.
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- -
icecast.xml) which defines all the configuration parameters for the server.
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
-source password - from
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
/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.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)
<mount type="default">to work properly.
<video>use cases and accessing the JSON status API.
<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
<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
<dump-file>. Disabled for Win32
server_start_iso8601to statitics. ISO8601 compliante timestamps for statistics. Should make usage in e.g. JSON much easier. Added as new variables to avoid breaking backwards compatibility
header_prefixto URL based listener auth
type-attribute is set
status2.xslfrom 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.- -
<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.- - -
<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.
icecastfollowed 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.- -
/streambut can be overridden here to use an alternative name which may include an extension that some clients -require for certain formats.
shoutcast-compatapproach as this implicitly -defines the second listening socket and allows for specifying multiple sockets using different mountpoints for -shoutcast source clients. The
shoutcast-mountoutside of a
listen-socketgroup is the global setting of the -mountpoint to use.
shoutcast-compat. This means if you define
shoutcast-compat, then you will need to define a listen port -of
8000and 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.
nameis required and its value specifies the HTTP header field name.
valueis required and its value specifies the HTTP header field value.
statusis 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
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-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-password> values in the config file. The server that is being relayed
-does not need any special configuration.
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>
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.
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.
0so YP advertising -can occur however you may want to prevent it here if you intend listeners to connect to a local relay instead.
charset=parameter to the metadata update URL if they so wish.
-1indicating that it is up to the source client or relay to determine if this mountpoint -should advertise. A setting of
0will prevent any advertising and a setting of
1will 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.
nameis required and its value specifies the HTTP header field name.
valueis 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
access.logwill be created relative to this directory.
/var/share/icecast2, and a request for -
http://server:port/mp3/stuff.mp3comes in, then the file
/var/share/icecast2/mp3/stuff.mp3will 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,
error.log (where all log messages are placed), an
access.log (where all stream/admin/http requests are logged) and an
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.
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 printed
3: Info, Warn, Error messages are printed
2: Warn, Error messages are printed
1: 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.