Examining the XML Files
This chapter examines the syntax of the icecast.xml and ices.xml configuration files. These files lie at the heart of the icecast and ices streaming audio applications. It is here all changes to the streaming and encoding server takes place. Vanilla configuration files are used for purposes of clarification, while customized versions explain more special-ordered streaming needs. Sufficient details are provided so that any user can customize his or her XML file to fit his or her particular situation.
Icecast2 XML Configuration
The first configuration file looked at is the icecast.xml for use on a master streaming server. Because the changes needed to stream static files versus live audio are slight, the vanilla configuration file requires only minor editing work. The configuration file shown here is that which is used when inserting raw or live audio to an icecast server or one that is used later for relaying purposes.
The following sample configuration is normally stored in the /usr/local/icecast2/conf directory. As described in the previous chapters, this file can technically be stored anywhere on the master icecast server. The default location is the /usr/local/share/icecast directory, but can be anywhere on the system. It is referenced only when starting the icecast server. Some developers recommend placing it in the /etc directory.
The following file is identified with the name icecast.xml. It can be modified to identify your own system and its purpose, i.e. icecast.ksl.live.xml. If you are only configuring a single streaming server the default name might work fine.
An Example icecast.xml File
The syntax for this customized icecast.xml file is similar to that of the distribution file. Though each field is fairly straightforward, some default configurations provide a cohesive and detailed explanation of each variable. The Icecast Project page has a detailed FAQ as well as documentation about each field:
Example 1. Example Icecast2 icecast.xml Files
<icecast>
<limits>
<clients>100</clients>
<sources>5</sources>
<threadpool>5</threadpool>
<queue-size>102400</queue-size>
<client-timeout>30</client-timeout>
<header-timeout>15</header-timeout>
<source-timeout>10</source-timeout>
</limits>
<authentication>
<source-password>password_01</source-password>
<relay-password>password_02</relay-password>
<admin-user>admin</admin-user>
<admin-password>password_03</admin-password>
</authentication>
<!-- <directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://dir.xiph.org/cgi-bin/yp-cgi</yp-url>
</directory>
<directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://www.oddsock.org/cgi-bin/yp-cgi</yp-url>
</directory> -->
<hostname>xx.xxx.xxx.xx</hostname>
<!-- You can use these two if you only want a single listener -->
<!--<port>8000</port> -->
<!--<bind-address>127.0.0.1</bind-address>-->
<listen-socket>
<port>8000</port>
<!-- <bind-address>127.0.0.1</bind-address> -->
</listen-socket>
<!-- <listen-socket>
<port>8001</port>
</listen-socket> -->
<!--<master-server>127.0.0.1</master-server>-->
<!--<master-server-port>8001</master-server-port>-->
<!--<master-update-interval>120</master-update-interval>-->
<!--<master-password>hackme</master-password>-->
<!-- <relay>
<server>127.0.0.1</server>
<port>8001</port>
<mount>/example.ogg</mount>
<local-mount>/different.ogg</local-mount>
<relay-shoutcast-metadata>0</relay-shoutcast-metadata>
</relay> -->
<!-- Only define a <mount> section if you want to use advanced options,
like alternative usernames or passwords -->
<!-- <mount>
<mount-name>/example-complex.ogg</mount-name>
<username>othersource</username>
<password>hackmemore</password>
<max-listeners>1</max-listeners>
<dump-file>/tmp/dump-example1.ogg</dump-file>
<fallback-mount>/example2.ogg</fallback-mount>
</mount> -->
<fileserve>1</fileserve>
<paths>
<basedir>/usr/local/icecast2</basedir>
<logdir>/usr/local/icecast2/logs</logdir>
<webroot>/usr/local/icecast2/web</webroot>
<adminroot>/usr/local/icecast2/admin</adminroot>
<pidfile>/usr/local/icecast2/icecast.pid</pidfile>
</paths>
<logging>
<accesslog>access.log</accesslog>
<errorlog>error.log</errorlog>
<loglevel>4</loglevel>
</logging>
<security>
<chroot>0</chroot>
<changeowner>
<user>iceuser</user>
<group>iceuser</group>
</changeowner>
</security>
</icecast> |
Icecast2 Configuration Variables
This next sub-section explains what each element of the icecast2 configuration file does. It demonstrates some possible variables based on the example shown above. Portions of the information presented here have been borrowed from the icecast documentation on the icecast home page.
Limits
This is the first section of a typical icecast.xml configuration file. This section specifies the basics as to how many listeners can connect to an icecast stream.
<limits>
<clients>100</clients>
<sources>5</sources>
<threadpool>5</threadpool>
<queue-size>102400</queue-size>
<client-timeout>30</client-timeout>
<header-timeout>15</header-timeout>
<source-timeout>10</source-timeout>
</limits> |
Each sub-section is explained in more detail below. Where possible I have kept the default value, except where a more cautious approach is warranted.
- clients
Set the specific number of available streams to which listeners can connect. This is an absolute value. Icecast sends an error message back to the 101st listener attempting to connect informing him or her that there are no more available streams.
- sources
This variable states the number of connected sources handled by the icecast program. These are the icecast sources that are relayed to other systems or icecast machines. If the value is too low and you are attempting to send out multiple streams, the program generates an error. The default value is normally "2."
For example, while attempting to implement DarkIce with two Ogg Vorbis streams of varying bitrates along with two different MP3 streams, the number of sources is set at the default value, or "2." The program does not generate the additional streams. After setting the value at "5," all four streams are created. Increment the default value as needed.
- threadpool
The number of threads started to handle client connections. If managing a high volume icecast server and people are constantly connecting and disconnecting, set this value to a higher number to accommodate the larger traffic amount. The recommended value is for a small to medium traffic server.
Consider this value to act much like the default threads created by Apache when initializing. This is the number of parent threads that can immediately handle incoming connections.
- queue-size
The maximum size (in bytes) of a client or listener's queue. The internal queue prevents too much lag time or drop-offs due to network congestion. If the queue becomes larger than this configuration value, the listener is subsequently removed from the stream. Consider using the default settings here.
- client-timeout
According to the icecast page this field is currently not in use. It can be ignored or left alone for the present time.
- header-timeout
The maximum time to wait in seconds for a request to arrive once a client has made a connection to the server. This value normally does not need to be changed.
- source-timeout
If a connected source does not send any data within this timeout period (measured in seconds) the source connection is removed from the server.
Authentication
This is the next section of a standard icecast.xml configuration file. This section specifies how streams authenticate to other streams and how administrators manage the audio feed.
<authentication>
<source-password>password_01</source-password>
<relay-password>password_02</relay-password>
<admin-user>admin</admin-user>
<admin-password>password_03</admin-password>
</authentication> |
Here is a breakdown of each individual field.
- source-password
Currently, icecast2 supports only unencrypted passwords. Enter the unique password here for all source streams. Some may opt to have all passwords be the same for relaying and administration. The recommended method is to use varying passwords for each method of connection.
- relay-password
The password used by the local icecast2 server and by other icecast2 servers pulling audio data off the local machine. Both local and remote machines must have matching relay passwords in order for relaying to work. Choose something not easily guessed by others or else you may find other icecast2 servers out there serving up your audio data.
- admin-user
The name of the administrator managing the icecast stream. By default this is normally "admin." This is also the username used for logging into the local XSL-based icecast site.
- admin-password
The password used by the admin user for all administrative functions. These include retrieving statistics, accessing the web-based administration screens, moving users, and so forth. A full list of these functions is still pending.
YP Directory Settings
This next section is commented out in my own settings since I do not wish to publicize my audio stream. Other users may wish to enable this setting depending on the amount of listeners they are attempting to solicit. Insert the correct variables that fit your stream's description.
This section contains all the settings for listing a stream on any of the icecast2 YP directory servers. This section may contain multiple listings to be specified in order as listed on multiple directory servers. The example below has two different YP directory listings. Use one or both or add additional listings.
<!-- <directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://dir.xiph.org/cgi-bin/yp-cgi</yp-url>
</directory>
<directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://www.oddsock.org/cgi-bin/yp-cgi</yp-url>
</directory> --> |
These items are designed specifically for users who wish to publicize their streaming audio server on the public Yellow Pages directories. By doing so they risk attracting a much larger listening audience with all the bandwidth consumption this may imply.
- yp-url-timeout
The maximum time in seconds the icecast2 server waits for a response from a particular directory server. The recommended value should be sufficient for most directory servers.
- yp-url
Icecast2 uses this URL to communicate with the YP directory server. The value for this setting is provided by the owner of the directory server. Talk to the directory server's administrator beforehand.
Miscellaneous Server Settings
This section covers any other server settings. Note that multiple listen-socket sections may be configured in order to have icecast2 listen on multiple network interfaces. If a bind-address option is not specified for a particular listen-socket, then the hostname parameter is used to specify the address to which it is bound.
<hostname>xx.xxx.xxx.xx</hostname>
<!-- You can use these two if you only want a single listener -->
<!--<port>8000</port> -->
<!--<bind-address>127.0.0.1</bind-address>-->
<listen-socket>
<port>8000</port>
<!-- <bind-address>127.0.0.1</bind-address> -->
</listen-socket>
<!-- <listen-socket>
<port>8001</port>
</listen-socket> --> |
This section explains each line of the port and socket settings. Pay close attention to these items as either one or the other should be left commented.
- hostname
Set the machine's local hostname. This can be a Fully Qualified Domain Name (FQDN) or an IP address. For testing purposes it can also be "localhost" or "127.0.0.1." In the example the machine's IP address has been replaced with X's. Substitute your own settings for this field.
- port
The TCP port used for accepting client connections. The default setting is 8000. Other port settings include 8001, 8010 or a port value grater than 8000. You are free to use what you want, within limitations.
- bind-address
An additional option whereby an IP address can be bound to a specific network card. If not supplied, the hostname variable is used.
- listen-socket
This variable is normally left commented out. It is used for specifying alternate port numbers on which the icecast server then listens. Viable ports include 8001 and up.
Relay Settings
This section explains how to configure an icecast server's relay settings. There are two types of relays: a master server relay or a specific mountpoint relay. A master server relay is only supported between two or more icecast2 servers and is used to relay all mountpoints on a remote icecast2 server. A specific mountpoint relay, on the other hand, is used for pulling a single audio feed or multiple audio feeds off a master icecast2 server and then streaming all available mountpoints on the remote box on the slave system. I have had the most success with the latter option and have found it to work extremely well.
This section covers the two different relaying methods. The first section handles the master server relay, while the second deals with a specific mountpoint relay. Pay close attention as to which type of relay is used in your configuration. It should be either one or the other.
Master Server Relay
Here is a typical layout of a master server relay setup. The values listed here are for demonstrative purposes only. Input your own values in the shown fields.
<master-server>127.0.0.1</master-server> <master-server-port>8000</master-server-port> <master-update-interval>120</master-update-interval> <master-password>letmein</master-password> |
The following diagram describes the basics of configuring a master server relay. Server beta, acts as the relay server, is configured with the <master-server>, <master-server-port>, and related settings. Server alpha, meanwhile, is the master server and the one from which server one pulls all attached mountpoints and subsequently relays them on to other listeners connecting to it. Using a master server relay, all mountpoints on server two are relayed. If only specific mountpoints need to be relayed, then you must configure server beta as a "specific mountpoint relay." Both master server relays and specific mountpoint relays begin their "relaying" when the server is started.
|-----| |-----|
| | all mountpoints | | /mount1.ogg
| | <------------------------ | | /mount2.ogg
|-----| |-----| /mount3.ogg
icecast2 icecast2
Beta Server Alpha Server
(Relay Server) (Master Server)
configured with
<master-server>
settings |
It is the slave/relay server or the one performing the relaying from a master icecast2 server that contains the master server relay settings. These settings contain the variables <master-server>, <master-server-port>, <master-updateinterval>, and the <master-password> values in the configuration file. The server that is being relayed, or the master server (alpha server) containing the original audio files or streaming the original audio content, does not need any special configuration settings.
 | Any slave or relay server attempting to connect to a master server must know the password and port number of the master server. Hence it is important to keep the password as complex as possible. Using a unique port also helps. |
- master-server
The IP address or Fully Qualified Domain Name of the server containing the mountpoints to be relayed. This is normally the IP address of the master server. Be careful to differentiate between the IP address of the relay server or the box on which you are adding these configuration changes and the master server from which you extract the audio stream.
- master-server-port
The TCP port of the server containing the relay mountpoints. This again reflects back on the master server. The default port is normally 8000.
- master-update-interval
The interval (in seconds) that the relay server (or beta server in the above diagram) polls the master server (or alpha server) for new mountpoints to relay.
- master-password
The admin password on the master server used for querying the server for a list of mountpoints to relay. This password uses plain text, so exercise caution here as well. Choose a secure password not easily guessed. Do not use the default password included with the distribution files. Change this value immediately.
Specific Mountpoint Relays
This section contains settings that apply to configuring remote mountpoints on relay servers. This is the option I normally use when relaying from a source server out to other relay machines. These settings are applied on the relay machine itself. When using these settings the other master-server relay settings should be commented out.
<relay>
<server>xx.xxx.xxx.xx</server>
<port>8000</port>
<mount>/source.ogg</mount>
<local-mount>/relay.ogg</local-mount>
<relay-shoutcast-metadata>0</relay-shoutcast-metadata>
</relay> |
The following diagram demonstrates the basics of a specific mountpoint relay. Note that server beta is configured with the <relay> settings and server alpha is the server from which server beta pulls the specified mountpoint(s) and relays them. Listeners connect to server beta for the audio stream. Using a specific mountpoint relay only those mountpoints specified on server alpha are relayed to server beta.
|-----| |-----|
| | /mount3.ogg | | /mount1.ogg
| | <------------------- | | /mount2.ogg
|-----| |-----| /mount3.ogg
icecast2 icecast2/shoutcast/icecast1
Beta Server Alpha Server
(Relay Server) (Remote Server)
configured with
<relay>
settings |
Specific mountpoint relays can be configured to relay from an icecast2 server, as well as from an icecast1.x and/or shoutcast server. A server is configured as a specific mountpoint server relay by specifying a <relay> XML entry in the configuration file for each mountpoint to be relayed. The server being relayed does not require any special configuration.
- server
The IP address of the server containing the mountpoint to be relayed. This refers to the source server or the remote server as shown in the above diagram. Remember that this entry must reside in the relay server so it knows from whence to pull the mountpoint.
- port
The TCP port of the server containing the mountpoint to be relayed. The default here is port 8000.
- mount
The mountpoint on the remote server. If relaying a shoutcast stream, this value must be "/." This is the mountpoint determined on the remote machine carrying the original stream to pass along to the relay server.
- local-mount
The name used as the local mountpoint or the mount name on the relay server. It can have a different mountpoint name, though some use the same mountpoint for purposes of convenience. This applies only relaying master icecast2 servers to other icecast2 relay servers.
- relay-shoutcast-metadata
If relaying a shoutcast stream specify this indicator to also relay the metadata (song titles) that is part of the shoutcast stream (1=enabled, 0=disabled).
Mount Specific Settings
This section contains settings applicable only to a specific mountpoint. This portion of the XML code reserves a specific mountpoint and sets a source username/password for that mountpoint (not yet implemented). It also specifies individual settings that apply only to the supplied mountpoint.
<mount>
<mount-name>/example-complex.ogg<mount-name>
<username>othersource<username>
<password>hackmemore<password>
<max-listeners>1<max-listeners>
<dump-file>/tmp/dump-example1.ogg<dump-file>
<fallback-mount>example2.ogg<fallback-mount>
<mount> |
The next few points clarify the fields listed in the previous example.
- mount-name
The name of the mount point for which these settings apply.
- username
An optional value that sets the username a source uses to connect via this mountpoint.
- password
An optional value that sets the password a source uses to connect via this mountpoint.
- max-listeners
An optional value that sets the maximum number of listeners that can attach via this mountpoint.
- dump-file
Yet another optional value that sets the filename for a dump of the stream entering through this mountpoint.
- fallback-mount
A mountpoint used in case of a source disconnect. If listeners are connected to the mount specified by the <mount-name> configuration value, and if the source disconnects, then all currently connected clients are moved to the fallback-mount.
Path Settings
This section contains the paths used for various directories within icecast. This is typically where configuration, log and administrative files are determined. note that there should be no trailing slash or "/" at the end of each path.
<paths>
<basedir>/usr/local/icecast2</basedir>
<logdir>/usr/local/icecast2/logs</logdir>
<webroot>/usr/local/icecast2/web</webroot>
<adminroot>/usr/local/icecast2/admin</adminroot>
<pidfile>/usr/local/icecast2/icecast.pid</pidfile>
<alias source="/foo" dest="/bar"/>
</paths> |
Here is the breakdown of each line within this portion of the XML configuration file.
- basedir
Used in conjunction with the chroot settings; it specifies the chrooted base directory when the server starts. This feature is not supported on win32 releases.
- logdir
Specifies the base directory used for logging. Both the error.log and access.log should be created relative to this directory.
- webroot
Determines the base directory for all static file requests. This directory can contain all standard file types (including MP3s and Ogg Vorbis files). For example, if the webroot variable is set to /var/share/icecast2, and a request for http://server:port/mp3/example.mp3 is received by the icecast server then the file /var/share/icecast2/mp3/example.mp3 is subsequently served.
- adminroot
This path specifies the base directory for all administrative requests. More specifically, it is used to hold the XSLT scripts used for the web-based admin interface. The admin directory included with the icecast distribution contains these files.
- pidfile
Specifies the file to write at startup and to remove during a normal shutdown. The file contains the process ID or PID of the icecast process. This can be read and used for sending signals to icecast.
- alias source="/foo" dest="/bar"
Aliases are used to create multiple mountpoints, all of which refer back to the same mountpoint.
Logging Settings
This section contains information relating to logging within icecast. There are two log files currently generated by icecast, an error.log, where all log messages are placed, and an access.log, where all stream/admin/http requests are logged.
<logging>
<accesslog>access.log</accesslog>
<errorlog>error.log</errorlog>
<loglevel>4</loglevel>
</logging> |
On non-win32 platforms a HUP signal can be sent to icecast in which the log files are re-opened for appending data, giving the user the ability to move or remove log files.
- accesslog
All requests made to the icecast2 are logged to this file. This file is relative to the path specified by the <logdir> configuration value.
- errorlog
All icecast generated log messages are written to this file. If the log level is set too high (debug level, for instance) this file can grow fairly large over time. Currently, there is no log-rotation scheme implemented in icecast. However, using one of the many Linux utilities, such as logrotate, you can achieve the same functionality and rotate the log files before they become too big.
- loglevel
Indicates what messages are logged by icecast. Log messages are categorized into one of 4 types; debug, info, warn, and error.
The following mapping can be used to set the appropriate value:
# loglevel = 4 - Debug, Info, Warn, Error messages are printed. # loglevel = 3 - Info, Warn, Error messages are printed. # loglevel = 2 - Warn, Error messages are printed. # loglevel = 1 - Error messages only are printed. |
Security Settings
This section examines the security settings available in the default icecast2 setup. These are by no means fool or hacker proof, but they do ensure a higher measure of security that would otherwise not be available.
<security>
<chroot>0</chroot>
<changeowner>
<user>iceuser</user>
<group>iceuser</group>
</changeowner>
</security> |
Here are the configuration settings used to secure the icecast server by performing a chroot to a secured location. This feature is not currently supported on win32 releases.
- chroot
An indicator specifying whether a chroot() is performed when the server is started. The chrooted path is specified by the <basedir> configuration value. The value 0 enables chroot, while 1 disables this feature.
- changeowner
This section indicates the user and group owning the icecast process upon startup. These require valid users present on the system. Custom users are recommended. These should be used specifically for running the icecast process and should have minimal rights to other applications on the system.