Editing the Icecast Configuration File

Server Location and Responsible Person

Define the physical location of your streaming audio server. This entry contains the server meta information. This data is displayed when listing directories, streams, and if the client supports it, other stream headers.

Server Limits

These items describe the maximum number of simultaneous connections allowed. Once the pre-defined limits are reached, the server refuses further connections. A builtin bandwidth measuring tool is included inside the icecast server. When icecast thinks that it is using more than the "throttle" Mb/s limit, no further clients or sources are allowed until the bandwidth usage returns below the defined limit. Use this option with caution since the icecast bandwidth measurement option is not an exact science.

Stream Meta Data

This section is an experimental feature. It provides the stream meta data to the client. Use caution when enabling these items as when it does not work, it may cause the entire stream to be out of sync on the client side, resulting in major audio issues.

Mountpoint Fallback

By default, if a user requests a stream that is not found, the default stream is handed off to the user instead. The default stream is per default the oldest stream on the server, but this can be changed using the priority value in the modify command. If you do not want the user to receive the default mount, but instead a HTTP 404 Stream Not Found error, set this value to "0".

Server Passwords

Unless icecast is compiled with crypt support, i.e. using the --with-crypt option as an argument to the configure script, all passwords are in cleartext. If the icecast server does have crypt support enabled, create an encrypted version of the password. This is done using the included mkpasswd.c program, which may or may not be included with this older deprecated release of icecast. Compile it using the following command: gcc -o mkpasswd mkpasswd.c. Consider using the the -lcrypt option.

Directory Servers

A directory server is a "meta-server" where icecast administrators can list their own icecast server gratis. This promotes an individual's streaming audio server and encourages more listeners to connect. The touch_freq option states how often the directory server should "update" with information from the local icecast server, e.g. the number of listeners, stream information, etc.

Server IP/Port Configuration

If a hostname is not specified, icecast listens on all available interfaces, i.e. INADDR_ANY. This is probably what you want. If you want icecast to only listen on a specific IP address, change the "hostname" parameter. The "port" parameter is self-explanatory. As of icecast 1.3.x, all connections use port 8000. No more messing with three different ports in the firewall rules.

The server_name option is specified only here, and only when starting the server. Changing it later does not have the desired effect. The server_name specifies the hostname of the server, so do not set it to an IP address. Using an IP address will probably work, but it does look nicer with a unique hostname. Also, changing the port here does affect the server when doing a rehash since binding to a port is done only once; when the server is started.

Users on dialup connections with dynamic IPs will experience difficulties. They will have to live without the virtual hosts support. There is no portable way of getting all the IP addresses to which the process is binding. Either edit this file before starting icecast and fill in the current IP address, or simply live with it. Setting the value to "dynamic", will tell the icecast server that there is no reliable hostname for this machine.

Administrators may also use multiple ports. The default port is the first one defined. Define the port variable, and then port+1 for shoutcast compatibility.

Directory Server Options

Force the directory server to use the server_name value instead of the originating IP address. This is unnecessary for most people, since this value is the same. For individuals behind proxies, however, this should be very useful.

Main Server Logfiles

These files specify the location of all icecast information regarding connections, warnings, errors, and so forth. This cannot be changed in the admin console, but changing it here and then rehashing the server does work.

Reverse Lookups

Perform reverse DNS lookups on all IP addresses connecting to the icecast server.

Console Mode

This option specifies how the icecast server is started, and how the icecast TTY is used when running the icecast server in console mode. This variable specifies the mode in which to display outputs to the icecast console.

Client Timeout

This section explains how to deal with clients when no encoder or streamer is connected.

Kicking Clients

This variable explains how to disconnect clients if a connection goes inactive.

Static File Directory

This enables HTTP file streaming support in icecast. If you don't want to go through the trouble of setting up apache or the web server of your choice, you can simply specify a directory here, and then your static file located at http://your_server:port/file/file.mp3 will be equivalent to the value /staticdir/file.mp3.

HTTP server support is very limited so do not attempt to do anything fancy until you have tested your configuration. Only .mp3 files will be displayed.

Templates

The icecast server uses templates to format output for the web page list.cgi and for various other icecast-related errors. Specify the directory from which these are read using absolute paths when possible.

Statistics

The icecast server keeps verbose statistics when running. View these either by using the stats command or by examining the contents of the file specified by the stats_log variable. Icecast regularly updates this file with listener statistics. It can easily be parsed to produce a nice output on a webpage on how many listeners are connected to the icecast server and so forth. This is generally done by using the list.cgi command within a web browser connected to the icecast server.

For example, to view listener statistics on a sample icecast server, place the following URL in a web browser: http://icecast.mydomain.com:8000/list.cgi.

The statshtml_log is updated regularly and the contents are created by parsing templates/statistics.html file. Administrators can edit this file by hand and create a custom statistics file.

Aliases and Virtual Host Support

In icecast servers prior to the 1.3 release, a typical icecast server could function as a relay for another icecast server by simply acting as a client on the other server and then by serving audio to local clients. This was a quick and easy method of increasing the number of possible listeners to your broadcast. An administrator could build a tree-like structure of relays and broadcast to 1000 listeners without problem with the originating stream on a cable modem or on some other high speed Internet connection.

In icecast 1.3.0 and above, this procedure is made all the simpler. To relay a stream from another server, simply add an alias for that server. For example, to relay a broadcast originating from the identified as icecast.mydomain.com:8000/icecast through another machine simply enter the following value under the alias setting on the machine performing the relaying:

alias icecast http://icecast.mydomain.com:8000/icecast

What happens is that when a listeners connects to the local relay server and requests the /icecast stream, that icecast server connects as a client to the orginating icecast server or icecast.mydomain.com, and then feeds the original stream to the listener via the local "client" server.

All subsequent requests to the local server for the /icecast stream uses the same feed from then originating server, i.e. only one connection is made to the primary icecast server. Icecast automagically disconnects the link from the primary icecast server when no one is listening or is connected to the local server. In this manner no bandwidth is wasted.

The old functionality of adding a static relay is still available, but must still be done from the admin console. Type in the following command at the admin console:

relay pull http://icecast.mydomain.com:8000/

This site will now be accessible as the following:

http://your_machine:port/icecast.mydomain.com:8000/

This can be modified using the -m option to relay pull.

There is also a possibity of doing this the other way around, starting at the originating server and doing a "push". Simply type the following:

relay push <source_id> host:port

The primary stream is then relayed to a remote server. In theory, this should enable virtual host support, as users can then specify an alias in the following manner within the configuration file:

alias http://virtual.host.com:port/whatever /something

This forces all requests to virtual.host.com:port/whatever to use the stream /something. This has not been thorougly tested, but it should work if the server_name value is correctly set, and the client is sending the valid Host: <host:port> HTTP header.

Kick Relays

This section explains how long to keep aliased sources when no clients are left listening to it.

Transparent Proxy

This is equivalent to forcing all requests to aliased sources. Instead of adding an alias for all the streams throughout the world, enable transparent proxy support. Using this on a server with streams of its own can be quite tricky. As usual it is very important the server_name variable is correct.

Most MP3 clients have support for listing HTTP proxies, i.e. x11amp and winamp. If listeners set your machine as their proxy for their MP3 client and you enable transparent_proxy, when a client requests http://whatever.com:port/whatever, your icecast server then connects to the whatever.com icecast server and feeds the whatever-stream to the client. All subsequent requests for this stream also use the same feed, just as if it were an alias.

When running icecast with your own broadcasts, this option should be turned off or anyone can bring your network down with multiple relaying connects. Do not turn this option on if you don't have a proper and valid server_name variable set.

Access Control Lists

Icecast has two different methods of limiting who connects to the server. The first is by using libwrap, tcpd, tcp wrappers, or whatever you want to call it. It is a separate library written by Wietse Venema that over the years has become more or less a security standard in Unix. It should compile on every sane Unix platform.

libwrap uses the files hosts.deny and hosts.allow, usually found in the /etc or /usr/local/etc directories. You normally must be root to edit these files. Try the man pages for tcpd and hosts_access for more information.

There are four different icecast control items to use in hosts.deny/allow. first, simply add "icecast", which controls all connections, and are enabled before anything is written or read on the socket. If a connection is denied here then the connection request is dropped. If allowed, then depending on the type of the connection whether it be admin or client or source, the controls "icecast_client", "icecast_admin", "icecast_source" describes who is allowed in. To deny all clients except those matching *.edu, add the following to the hosts.deny file:

icecast_client: ALL EXCEPT *.edu

There are many different variations on how to build a complete defence. libwrap is a very powerful tool. Consult the manpages for more information.

The second method, though not always available, is to use icecast's internal acl lists. The functionality is the same, but it is not as powerful as libwrap when it comes to configuration and flexibilty. Specify acl rules either here in the icecast.conf file, or by using the admin console.

The acl syntax in icecast.conf is as follows:

allow <all|client|source|admin> <hostmask>
deny >all|client|source|admin> <hostmask>

When using a variation on the same rule as shown above, or by allowing only clients from *.edu domains, here is how acl rules would be added to the icecast.conf file or via the admin console:

deny <client> *
allow <client> *.edu

When using internal acl rules under icecast, specify a policy. This rule kicks in when there is no allow or deny rule affecting a connection. If you set the acl_policy variable to "0", connections that are not allowed by any allow rule are then denied. The same applies the other way around if the variable is set to "1".

Consult the comments included with the default configuration file for any additional items or information. Be aware that this icecast release is deprecated and is no longer supported by the icecast development team. Consult the included documentation files in regards to any questions you may have about these configuration items.