1. Building
    1. Downloading
      1. Latest release
      2. Precompiled packages
      3. CVS
      4. Snapshots
    2. Unpacking
    3. Compiling
      1. Running configure
      2. Compile time settings
      3. Running make
  2. Configuring
    1. Command line options
    2. Configuration file (icecast.conf)
  3. Running
    1. Client
      1. Windows clients
      2. Unix clients
      3. Mac clients
    2. Source
      1. Shout
      2. Liveice
      3. Iceplay
      4. Winamp
    3. Admin
      1. Connecting the admin
      2. Admin Commands
    4. Directory servers
    5. Relaying
    6. Static files
    7. Statistics
    8. Access Control
    9. Template HTML files


    1. Building

      This section describes where and how to download, unpack and compile your icecast system. I suggest you read it very carefully, especially the Compiling chapter. Installing icecast is a simple procedure, no special magic involved. But to make the most of your icecast system, and understand the fundamental parts of the server and encoding streamers, it will help to know this chapter by heart.

      1. Downloading

        This section describes how to get the sources, or precompiled binaries, that you need to run icecast.
        There are some other tools that can help you broadcast, and in time, they will get listed here as well. To make a long story short, what you need to run an icecast system, is the icecast server, called icecast and an encoder (shout, liveice, winamp, iceplay). All except winamp are included in the icecast system.

        1. Latest release

          When the icecast team thinks the development version is stable enough for the big public, they create a release. Example of releases are icecast-1.1.4, and icecast-1.3. Icecast versions follow the standard set by the linux kernel. Odd numbers are development releases, and even numbers are stable. So icecast 1.0 was stable, 1.1 was development, 1.2 would have been stable if we ever got around to releasing it, and 1.3 is development. When 1.3 is stable enough, we will call it 1.4 or perhaps 2.0 and move the development tree to 1.5 (or 2.1). A bit confusing.. I agree :)
          To get the latest snapshot, go to www.icecast.org and click on downloads.

        2. Precompiled packages

          For some reason, people are lazy. Some people wants the system up and running without going through the compiling and compile time configuring stuff. That's why we supply precompiled packages in various formats for various platforms. We don't build all of these ourselves, but rely on other people to send them to us. If we can, we test them and make sure they work, but we offer no guarantees. For the big releases, such as 1.3, we hope to provide rpms, debs, and tarballs for most systems. If you build icecast for a platform for which there does not exist any precompiled packages, then it would be a great help for us if we could distribute that. Provided that it works :)
          You get the precompiled binaries at www.icecast.org, click on downloads.

        3. CVS (the cutting edge)

          Releases don't happen that often. We really try to keep them regular though, but there still might be a couple of months between the major ones. And I know some of you, like me, like to keep up with the absolutely latest source available. And the great thing is that you can :)
          Icecast developers use the CVS system to keep the source code in a separate repository so that all developers can use the same code at the same time (more or less).
          You too, can use CVS to get the latest sources. If you like to contribute to the sources, then notify team@icecast.org, and we'll add a cvs account for you. If you just want to get the sources, then get the cvs system from www.cyclic.com and follow this procedure:
          export CVSROOT='anonymous@cvs.icecast.org:/cvsroot'
          cvs login
          There is no password, just press enter.
          cvs -z3 checkout icecast-1.3
          And your done. Please note cvs sources are not stable, they change all the time and therefor might not build, or the server might crash. Also, you might note that there is no configure script. Use the autoconf program to create configure. Autoconf can be downloaded from your closest GNU archive.

        4. Snapshots

          For those of you who don't want to, or for some reason can't, use the cvs system, we try to tar up more or less daily snapshots from the development tree. These should be a little bit more stable than the cvs sources, but don't be surprised if they don't build on your system. To get the latest icecast snapshot, go to www.icecast.org/snapshots/.

      2. Unpacking

        Once you get the icecast system, you first need to unpack it. If you downloaded a release or a snapshot, then this is done by first gunzipping and then untarring the package, or if you're using GNU tar, then just do: tar -zxvf icecast-.tar.gz.
        If you've downloaded a precompiled package, then you hopefully know how to install it yourself :)

      3. Compiling

        This section describes how to compile the icecast system. Step by step instructions, and what options you have.
        If you just want the default setup, this is very simple. If you want to tailor the system for you specific needs, then this is very simple too.

        1. Creating the Makefile with configure

          In the toplevel icecast directory, there should be a file called configure.
          If there is not, but there is a file called configure.in (you've downloaded the cvs sources or a snapshot), then you need to create the configure script with the autoconf program, without any flags or options.
          The configure script creates the Makefile. If you want the default setup, just run it with ./configure.
          There are two options to the configure script that you might want to enable. The first is --with-libwrap, which enables support for Wietse Venema's tcp wrappers. See the section about access controll below.
          The second is --with-crypt, which means that the passwords you specify in icecast.conf and on the command line when running the icecast server should be in encrypted form. To create these encrypted passwords, there's a program called mkpasswd included in the distribution. No other options to the configure script make any difference.

        2. Compile time settings

          This section describes what you can change in the Makefile and icecast.h to optimize performance and change the default behavior of the icecast system. You do _not_ have to go through this step if you just want the default setup.
          This step is optional.

          1. Editing the Makefile

            You need to edit the Makefile if you are not using gcc as compiler and want some compiler specific flags, or if you want to change some architecture specific compiler flags, e.g for optimization.
            The first two lines describe the compile being used (CC), and the compiler flags (CFLAGS). Change these to whatever is best on your system.
            For example, I use CC=egcs and CFLAGS= -O5 -march=i686 -mcpu=i686 -fstrict-aliasing.
            Depending on which version of icecast you've got, there might be some extra defines you can set in the Makefile. For the 1.3 release, these are -DOPTIMIZE, -DSAVE_CPU, and -DMEMORY_DEBUG
            -DSAVE_CPU turns off tracing mutex locks and unlocks. This means you will not be able to track down a deadlock caused by bad mutex locking. But it will make your server use less cpu.
            -DOPTIMIZE will turn off a lot of debugging output, and it does make a lot of difference in cpu time. Think twice about defining this, cause when it is defined, you won't get any debug output from icecast at all, so when something goes wrong, you won't know.
            -DMEMORY_DEBUG will turn off memory tracing and all kinds of neat memory debug stuff, only useful for development versions of icecast. If you want to know where all the dynamically allocated memory goes, turn this on.

          2. Editing icecast.h

            icecast.h contains all the default settings for the icecast server. Most of these you can change when you run the program, but some are hard coded in the binary. If you change anything in icecast.h, then you are not in any position to claim bugs or performance issues in icecast.
            Specifically, if your system can handle large chunks of data for read() and write() system calls, then increase the SOURCE_BUFFSIZE and CLIENT_BUFFSIZE. Bigger bufsizes means less system calls, and on most systems this will mean less cpu usage.

        3. Compiling (running Make)

          Now it's time to run make. icecast has been developed using gnu make, but we don't do anything fancy in the Makefiles, so any make should be fine. If you encounter Makefile specific problems then notify devel@icecast.org.
          Type 'make', and off we go. This will compile icecast (the server) and shout. If you want Liveice, go into the liveice directory and follow the instructions there. Liveice might not compile on your system though, it only supports Linux and FreeBSD as of now (afaik).
          If you get _any_ errors or warnings while compiling icecast, you should notify devel@icecast.org. We want the compilation procedure to be 100% clean on all platforms.
          If you really want to, you can run 'make install', which will copy icecast files to /usr/local/icecast (if not otherwize specified). But I would suggest keeping everything in the place where you unpacked and compiled. Icecast by default creates the logfiles and looks for the configuration files in the log directory, or, if log does not exist, in the current directory.

          If you do use 'make install', the icecast binaries will end up in /usr/local/icecast/bin, the configuration file (icecast.conf) will be in /usr/local/icecast/etc. The logs will be created in /usr/local/icecast/log, and templates for the html-pages created by icecast will be in /usr/local/icecast/templates.

    2. Configuring

      The following configuration is for the icecast server only. For liveice and shout configuration, follow the links from the liveice and shout sections below.

      1. Command line options

        The following command line parameters can be given when you start the icecast server. Command line parameters override all configuration file parameters (icecast.conf), which in turn override the default compile time settings.

        • -c [filename]

          Parse as a configuration file. Please note that any command line parameters you supply after this override whatever is in file. Also note that icecast.conf in the current directory is already parsed when you specify this file, so anything in icecast.conf not overriden by the new configuration file will be used by the server.

        • -P [port]

          This is the port used for all client, source, and admin connections. It's set to 8000 by default.

        • -m [max clients]

          Allow this number of client connections. When this number is reached, all client connections will be refused with 'HTTP/1.0 504 Server Full'

        • -p [encoder password]

          This sets the password that the encoder must use to be allowed to stream to the server. Note that if you have compiled the server with crypt() support, this argument must be an encrypted string.

        • -b

          This will send the icecast server into the background (i.e daemon process). To use the admin commands now, you have to connect to the server as an admin, using some sort of telnet client.

        • -d [directory]

          Make all log files created by icecast, and all templates that icecast looks for be relative to this directory.

      2. Configuration file (icecast.conf)

        This section describes the configuration parameters inside icecast main configuration file, icecast.conf. The icecast.conf file should (if not otherwize specified with the -c command line option) reside in the current directory.
        More information about the parameters can be found inside the icecast.conf file itself. Comments lines start with a '#' sign as the first character in the line, the rest of the line is ignored.
        Configuration parameters are specified as 'parametername parameter', where parametername is a string without spaces and parameter is the rest of the line. Never enclose the parameter in double quotes ("").

        • location

          This should be set to the geographic location of the icecast server. It's just for show, and doesn't really matter. But it's still a nice way for listeners to know where in the world the server is located.
          No syntactic controls apply, but if you want to follow the standard, use 'STATE, COUNTRY', or 'CITY, COUNTRY'.

        • rp_email

          This should be set to the email adress of the admin running the server.

        • server_url

          This should be set to a URL describing this icecast server.

        • max_clients

          The maximum number of simultaneous clients connected to the server.

        • max_clients_per_source

          The maximum number of simultaneous clients connected to the same stream on the server. Setting this to a value bigger than max_clients does not make any sense.

        • max_sources

          Max. number of simultaneous sources connected to the server.

        • max_admins

          Max. number of simultaneous connected admins.

        • throttle

          Specified in Megabytes per second. How much bandwidth the server is allowed to use up before client and source access is denied. Use this with caution since the internal bandwidth measurement is not an exact science.

        • client_password

          This is not implemented yet, but in the future it will be a password that the clients will have to specify to get access to the server.

        • encoder_password

          This is the password by which the server accepts encoders and relays.

        • admin_password

          The password needed for admins to be accepted to the admin console

        • oper_password

          This is the password an admin must specify to get access to the sensitive server operator commands

        • directory

          The syntax is 'directory directory.host.domain:port/path/to/icedir/program', or 'directory directory.host.domain:port', or 'directory directory.host.domain'. If not specified, the default port is 80, and the default icedir program is '/cgi-bin/xaudiocast-touch'
          Please note that this is the syntax for xaudiocast directory server. When you start using icecast, the xaudiocast directory server might not be fully functional. Use the icydir parameter for the 'old' directory server interface.

        • icydir

          This adds a icy directory server (such as yp.shoutcast.com). The syntax is simply 'icydir directory.host.domain'.

        • touch_freq

          This setting regulates how often the directory servers get 'touched' by the icecast server. This default setting of 5 minutes is a good value.

        • hostname

          You are probably better of leaving this setting alone. If NOT set, this will make icecast listen on all available interfaces (i.e all ips), but if you set it to a hostname or ip number, then icecast will _only_ listen on that ip. This is nice for people with 2 ips who want to run one icecast server on each. If you specify an invalid ip, then nothing will work.

        • server_name

          This is perhaps the most important setting in icecast.conf. It's the name of the server. It SHOULD be set to an ip, or preferably a hostname that points to your ip. If not, then lots and lots of stuff will not work and it might even break your server. For instance, my ip is 130.236.235.105, which is d105.ryd.student.liu.se, so I set the server_name to d105.ryd.student.liu.se.

        • port

          This is the port the icecast server uses for all connections. Admins, clients, and sources, they all connect to this port. The old behavior, having the clients on 8000 and the encoder on 8001, is too ugly and creates some problems with firewalls and so. The new behavior might confuse streamers such as winamp. WinAMP is stupid enough to connect to the specified port + 1. So if you set the port (in WinAMP) to 8000, it will connect to 8001. Setting it to 7999 will work though.

        • logfile

          This file, icecast.log in the current directory by default, is what the icecast server uses as logfile. Everything goes in here, so it might grow quite big. Also, when you restart the server, it will not truncate this file. So it might be a good idea to empty the file before each run of icecast.

        • logfiledebuglevel

          This setting regulates what level of debugging output is written to the logfile. A higher value means more debugging output. 0 means no debugging output, 1 and 2 is pretty ok, 3 and 4 will spam it will shitload of stuff :)

        • consoledebuglevel

          This is the same as logfiledebuglevel, but regulates the output on the icecast console

        • reverse_lookups

          When this is set to 1, icecast will try to reverse all ips to hostnames. This might take some time and consume some extra cpu, but it will make logfiles and all other output look much nicer. Setting this to 0 will turn the reverse lookups off.

        • console_mode

          This sets how the icecast server gets started, and what the tty you started icecast in will be used for.
          0 means use it as a admin console (you can send commands to the icecast server and stuff) with logfile info.
          1 is the same as 0 but without logfile info.
          2 means just use it as a logfile window.
          3 means put the icecast server in the background, as a daemon process.

        • client_timeout

          This setting regulates how long (in seconds) to keep clients connected to the server after their source has disconnected. Or, in other words, how long to wait for a source to come back to its old listeners.

        • kick_clients

          This regulates what happens to the clients when the client_timeout has expired. It only has an effect if client_timeout is more than 0. If you set kick_clients to 1, then they will get kicked off the server, but if you set it to 0, they will be moved to another stream, if there is one.

        • static_dir

          If you don't want to go through the hassle of setting up a http server as a means of putting your mp3 files up for public download, then there is limited support for this in icecast. See the section about Static files below.
          This sets what directory on disk will be the root for http://your.server.com:port/files/

        • stats_log

          The icecast server dumps statistics to a file on a regular basis. See the section about Statistics below.
          This sets what file is used for statistics.

        • stats_time

          This setting, in seconds, sets how often the statistics file gets updated.

        • alias

          Aliases can be used for 2 things. One is for a very flexible and powerful way of relaying streams on other icecast or shoutcast servers. See the section about Relaying below. The other is for having 2 mountpoints on the server refer to the same source. 'alias /cool /funkyassdancemusic' would add an alias named /cool which refers to the /funkyassdancemusic stream. It doesn't matter if no stream is actually mounted there now.

        • transparent_proxy

          This should be set to 0 unless you really really know what you are doing. Setting it to 1 will make the icecast server act as a proxy. See the section about Proxies below.

        • kick_relays

          When a remote source is mounted into the icecast server on a remote alias request, it will only keep the source connected while there is still someone listening. When all listeners has disconnected, it will keep the source for kick_relays seconds, and then kick it out. This saves a lot of bandwidth.

        • acl_policy

          This regulates whether connections are allowed or denied if no acl rule exists that affects them. See the section about Access Control below. Setting it to 0 will deny all these connections, and 1 will allow them.

        • allow

          This adds a hostmask for a specific type connection, which will be allowed access. Syntax is 'allow [type] [hostmask]'.
          See the section below on Access Control.

        • deny

          This adds a hostmask for a specifi type connection, which will be refused access.
          Syntax is 'deny [type] [hostmask]'.

        • use_meta_data

          This will enable title streaming functionality in the icecast server. Title streaming means that the file name of the song currently playing will be transfered to the icecast server, which in turn will tell the directory server and clients who support title streaming.
          If you experience regular chirps in the stream, try turning this off.

        • streamurl

          If the sources don't set a url for the stream, then this variable is the fallback

        • streamurllock

          If you don't want the sources to be able to change the url of their streams, set this to 1

        • streamtitletemplate

          This is a template for the stream title that is sent to the clients who support it, and to the directory servers. One occurence of "%s" will be replaced with the filename of the current song.

        • nametemplate

          This is a template for the name of each stream, as presented to the directory servers and clients. One occurence of "%s" will be replaced with the actual name of the stream.

        • desctemplate

          desctemplate is a template for the description string for each stream. One occurence of "%s" will be replaced with the actual description of the stream.

        • iceroot

          This is the root directory of the tree where icecast looks for the configuration files, log files, and html template files.

    3. Running

      This section describes and discusses the issues involved in running the icecast systems. Running clients, streamers, the admin console, and the server. It also takes up the various features of the system, such as access control, relaying, statistics, static files, etc...

      1. Client

        This chapter talks about the different clients you can use to connect and listen to a icecast stream. It tries to compare them, but to be honest, I haven't used them all and can only try to compare them using the information I have gathered from others.

        1. Windows clients
          • Winamp

            Developed by Nullsoft, Winamp is the most widely used mp3 player in the world. It is a stable audiocast client, and can also be used as a streamer. It does not (as of version 2.21) support x-audiocast headers.

          • Sonique

            A very cool client for windows. People say its even more stable than winamp when it comes to streaming. And it looks damn cool :)

        2. Unix clients
          • XMMS (formerly x11amp)

            A really cool mp3 player for Linux and FreeBSD (afaik). It has very stable streaming support, some support for x-audiocast headers and lots of more stream features.

          • mpg123

            Perhaps the most widely used mp3 player for unix. Command line driven, and with some limited support for audiocast streaming.

          • FreeAmp

            Getting more stable with every release, FreeAMP is also an option in the unix world.

        3. Mac clients

          Unfortunately, there is currently no Mac player available that supports audiocasted mp3 streams.

      2. Source

        This section lists some of the ways you have of sending data to the icecast server. This is called streaming, and the program that handles this is called a streamer, or an encoder, or a source. They can be devided into two groups. Re-encoding streamers, and static file streamers.
        Static file streamers simply reads the bitrate of the file it is going to send, and transfers it to the server at that speed. To send a mp3 file encoded at 64 kbit/s, 64 kbit/s bandwidth will be required. This theory is quite simple, but actually keeping this exact bitrate is not that easy. Static streaming requires almost no amount of cpu or memory resources.
        The other category is re-encoding streamers, and they read the mp3 file, decodes it to wav or raw pcm data, and then encodes this at a specified bitrate. This way you can take a 128 kbit/s mp3 file, and send it at 24 kbit/s. This will require a substancial amount of cpu resources on your machine, but it is the only way of doing real DJ:ing with beatmixing and Mic input.

        1. shout

          Shout is a static file streamer with a powerful playlist engine and a finely tuned transfer loop.
          It has a large number of command line and configuration file parameters. For more info about Shout see this README.
          Shout supports the new x-audiocast headers and is bundled with the icecast package.

        2. liveice

          Liveice is a re-encoding streamer, also bundled with the icecast package. It is quite powerful and supports a number of different encoders (xing, fraunhofer, etc..). You can mix several mp3 streams and the mic input, change speed and volume of the different streams.
          For more info about liveice, see this README.

        3. iceplay

          iceplay is the old icecast streamer. It's a static file streamer written in perl. It's bundled for history reasons :)

        4. winamp

          winamp is both a client and a streamer for Windows. It's a re-encoding streamer.

      3. Admin

        This section describes the admin console, how to connect and what commands are available.

        1. Connecting the admin

          To access the admin console, telnet to your icecast server (port 8000 by default). You can use the default telnet client, but if you're planning on doing any serious work, I suggest you use a more sophisticated client such as TinyFugue. With TF you can get color highlighting and command line editing.
          When you connect, nothing will be printed, no prompt, nothing. Then you type the following:
          'ADMIN [admin password]' followed by two newlines (press enter twice). Substitute the [admin password] for the admin password you've set in icecast.conf or with a command line parameter to icecast.

        2. Commands

          The following commands are available in the icecast admin console. Most of them requires icecast operator access though. To become an icecast operator, use the 'oper' command with the operator password as argument

          • alias

            The alias command is used for two things. You can add an alias for a local mountpoint so that a stream can be accessed from two mountpoints. Or you can add an alias for a remote icecast/shoutcast stream. See the section about relaying using aliases below.
            Syntax:
            alias add <mountpoint> <newmountpoint>
            alias del <mountpoint>
            alias list
            Examples:
            alias add /icy_0 /coolstream
            alias add /radiofri http://195.7.65.207:6903/

          • allow & deny

            This adds a hostmask to the internal acl lists. It specifies that this hostmask should be allowed or denied access. You specify a type for this acl, which can be either all, client, source or admin. It only has affect on the specified connection type.
            Syntax:
            allow|deny <client|source|admin|all> add <hostmask>
            allow|deny <client|source|admin|all> del <hostmask>
            allow|deny <client|source|admin|all> list
            Examples:
            allow client add *.se
            allow all del *.netcom.com
            deny admin add *.se
            deny admin del ap.*.com
            allow admin list

          • admins

            The 'admins' command is used to list the admins connected to the server. It will give output with one admin connection per line, like so:
            Admin 341 <d66.ryd.student.liu.se> connected for 1 hours, 8 minutes and 14 seconds. 0 commands issued. Flags:OTS - It's you! -
            The 'It's you!' part on the end means that this is the admin who issued the admins command, i.e you :)
            You can supply a hostmask as an argument, and then you will only get the admins who match the mask.
            Syntax:
            admins [hostmask]
            Examples:
            admins *.icecast.org

          • dir

            The dir command is used to add, remove or list the directory servers this icecast server is currently using. Adding icy as the last argument of a 'dir add' tells icecast that this is a icy server.
            Syntax:
            dir add <host[:port[/path/to/program]]> [icy]
            dir del <host>
            dir list
            Examples:
            dir add yp.shoutcast.com icy
            dir add yp.icecast.org:80/cgi-bin/xaudiocast_touch
            dir list
            dir del yp.icecast.org

          • dump

            Use this command to dump a connected stream to a file on disk. I have absolutely no idea why you would want to do this, but you can :)
            If the filename specified is 'close', then the file will be closed.
            Syntax:
            dump <source id> <filename|close>
            Examples:
            dump 230 /tmp/stream.mp3

          • help

            Perhaps the most helpful of all commands is 'help'. Without arguments it prints a list of all commands, and what they are used for. With a command as argument, it prints a slighly longer description of what the command does.
            Syntax:
            help [command]
            Examples:
            help kick
            help

          • kick

            Sometimes you want to get rid of some listeners, admins, or sources. Just kicking them out is the answer. You can kick out one connection, or all connections of a certain type matching a hostmask.
            Syntax:
            kick <id>
            kick <-acs> <hostmask>
            kick <hostmask>
            Examples:
            kick 314
            kick -a *.com
            kick *.nullsoft.com

          • listeners

            When you want to list all connected listeners, 'listeners' is the command you are looking for.
            You can list all, or those matching a hostmask.
            Syntax:
            listeners [hostmask]
            Examples:
            listeners *.frobnication.frob.org

          • modify

            When an encoder connects, it first specifies some information about the stream, such as bitrate, genre, name, url, etc. You can change this information with the 'modify' command.
            -m means mountpoint, -u means url, -n means name, -d means description, -g means genre, -p means public, -b means bitrate and -P priority
            The priority field is a number that is used when determining the default mountpoint for the server. The source with the highest priority value is the default mount point.
            Syntax:
            modify <source id> <-mungdpb> <new value>
            Examples:
            modify 23 -d The bluest blues you've ever heard
            modify 54 -m /coolblues

          • oper

            Most commands on the admin console are restricted to icecast server operators. To obtain operator privileges, you use the oper command with the icecast operator password as argument.
            Syntax:
            oper <operator password>
            Examples:
            oper cooloperpass

          • pause

            This is another command that has very limited use. You can cut the data flow to a client or from a source. It makes everything go quiet for a while.
            Syntax:
            pause <client or source id>
            Examples:
            pause 314

          • quit

            Use the 'quit' command to leave the icecast admin console. You can only do this if you are accessing the console through the remote interface (i.e using telnet). An optional argument will be used as a signoff message, i.e displayed to the other connected admins.
            Syntax:
            quit [message]
            Examples:
            quit Bye Bye

          • rehash

            When you have changed stuff in the icecast configuration file (icecast.conf), or want to read another file as a configuration file, you can use the 'rehash' command. When used with an argument it will use this argument as a filename and parse this as a configuration file.
            Syntax:
            rehash [filename]
            Examples:
            rehash /tmp/newicecast.conf

          • select

            'select' is useful when you want to transfer listeners from one stream to another. You can either transfer all clients connected to source A, to source B, or all clients connected to source A matching a pattern, to source B, or just client with a specified id, to a new source.
            Syntax:
            select <-a> <source source id> <target source id>
            select <client id> <source id>
            select <source source id> <hostmask> <target source id>
            Examples:
            select 514 23
            select -a 43 23
            select 23 *.se 43

          • sources

            'sources' is used just like 'listeners' to view all the connected sources. It can be used with an optional argument to limit the list to only the sources matching the hostmask specified.
            Syntax:
            sources [hostmask]
            Examples:
            sources *.apan.com

          • shutdown

            To shutdown the server you can use the 'shutdown' command. An optional argument can be given which will be used as a shutdown message broadcasted to the connected admins.
            Syntax:
            shutdown [message]
            Examples:
            shutdown Oh shit, oh shit, OH SHIT!

          • set

            Used without arguments, 'set' will display a list of all icecast server variables, and their current values. You can also use 'set' to change any of those variables, if you specify the name and the new value as arguments.
            Syntax:
            set
            set <variable name>
            set <variable name> <new value>
            Examples:
            set client_timeout
            set max_clients 580

          • stats

            The 'stats' command will print some information about the current number of connections, averages on client connections, bytes read and written, etc.. It looks a lot like the output printed to the statistics file. As an argument, you can put 'hourly' or 'daily', and then the averages and totals will be for the last hour or day only.
            Syntax:
            stats [hourly|daily]
            Examples:
            stats hourly

          • tail

            The 'tail' command can be issued by an admin to intercept messages written to the logfile.
            It's similar to the unix tail command.
            Syntax:
            tail
            Examples:
            tail

          • tell

            An admin can send a message to all other connected admins using the 'tell' command. Any arguments will get printed to all admins.
            Syntax:
            tell <message>
            Examples:
            tell This song really rox!

          • touch

            You can use the 'touch' command to force the icecast server to immediately touch all directory servers.
            Syntax:
            touch
            Examples:
            touch

          • unpause

            The 'unpause' commands unfreezes a client or stream previously paused with the 'pause' command.
            Syntax:
            unpause <client or source id>
            Examples:
            unpause 314

          • uptime

            The 'uptime' command is similar to the Unix uptime command. It prints the number of days, hours, minutes and seconds the icecast server has been running.
            Syntax:
            uptime
            Examples:
            uptime

          • list

            To list all connections. All sources, admins, and clients, then you should use the 'list' command.
            Syntax:
            list [hostmask]
            Examples:
            list *.toomanyarguments.com

          • relay

            To mount a remote stream on your icecast server, or to mount one of your local streams on a remote server, you should use the 'relay' command. See the section about Relaying below.
            Syntax:
            relay push <source id> <host[:port]> [options]
            Where options are:
            -p <password>
            -u <url>
            -m <mountpoint>
            -n <name>
            -g <genre>
            -P <public>
            -b <bitrate>
            -d <description>
            -i (means remote server is an icy server)
            relay pull [-m <localmount>] <url>
            Examples:
            relay push 314 ice.berg.org:7343 -p 3l33t -u www.icecast.org
            relay pull http://reall.y.co.ol:45500/cool

          • threads

            On systems where it is supported (i.e not windows), the 'threads' command will print a list of all the running threads, and what function and linenumber they were started from. It is useful for debugging.

          • locks

            On systems where it is supported, the 'locks' command will print a list of all mutexes in the server and show if they're locked or not, and if the they're locked, what thread has the lock.

          • status

            The 'status' command sets whether or not you get periodic information on bandwidth usage and number of client, admins, and source connected printed on your console.
            Syntax:
            status [off|on]
            Examples:
            status off

          • debug

            The 'debug' command changes the level of debugging output that this admin receives. The argument should be a positive integer. 0 means no debug output and 4 is the current max.
            Syntax:
            debug [digit]
            Examples:
            debug 3

      4. Directory servers

        This section talks about directory services, what they are and what they provide and the difference between them.

        1. What is a directory server?

          A directory server is a database with a list of icecast or shoutcast servers. It's usually accessed through a web interface. Try http://yp.icecast.org/ for instance. You get a list of all servers that are currently displaying information to this directory server. The information is updated on a regular basis, every 5 minutes per default. At the time I write this document, the icy directory servers are still dominating the world, and only one server is running with the x-audiocast protocol and that's a test server that I set up myself :)
          This should bloody well change though, because the x-audiocast protocol is much nicer, and when it comes to the directory servers, it enables functionality such as relay lists and multiple streams per server.

        2. How do I make my icecast server talk to a directory server?

          You can make your icecast server display information on any number of directory servers. You can either add new directory servers using the admin console and the 'dir' command, or add them in the configuration file with the 'dir' and 'icydir' paramaters.

      5. Relaying

        The idea behind relaying is that one server is limited by the bandwidth of his network connection. So even though I might have a 10 mbit connection to the internet, I still can't take in as many listeners as I want. Not to mention that the network administrators will nuke my swedish arse if they found out :)
        But, and this is where relays come in, if one of the connected listeners could send the stream to say 10 other listeners closer to him, then a lot more people would be able to enjoy my music. In the perfect world, you would have a treelike structure of relays distributing your stream all over the world. This is where you need a lot of friends with lots of bandwidth to waste ;)
        There are three types of relays in the icecast server. Pushing, pulling, and aliased relays (aka on demand relays)
        To make a long story short, a pushing relay is where an admin on the originating server connects one of the local streams to a remote server.
        A pulling relay is basicly the same, except that the request is sent from the remote server, which mounts a remote stream as a local stream.
        An aliased relay is special, and a very nice thing indeed. For those of you familiar with mount and automount in the unix environment, this is quite similar. Instead of keeping a remote stream on your server all the time, and wasting bandwidth when no one is listening, you add an alias on your server for a stream on a remote server. And when a client requests this stream on your server, then you connect and send him the stream.

        1. Pulling relays

          The admin on a remote server (aka slave server) issues the 'relay pull' command and the icecast server will connect to the originating (master) server as a client and then mount the stream as a local source. This has the advantage that you don't have to share any passwords.

        2. Pushing relays

          Pushing relays is where the admin on the master server issues the 'relay push' command and the icecast server connects to the remote (slave) server as a source.

        3. Relaying using aliases

          Aliases for remote streams are added with the 'alias add' command or using the alias parameter in the icecast.conf file.
          When a client requests a stream which is an alias refering to a remote stream, the icecast server will connect to this remote server and mount this stream in as a local source, just like a relay pull. When no clients are longer listening to this stream, the server will kill this source, to save bandwidth.

        4. Proxy

          You can setup your icecast server as a proxy, which means that all requests for streams on remote hosts will be make the icecast server mount the remote streams as local sources, just like aliases. Proxy mode is just like adding an alias for each and every audiocast in the world. Please not that it is very important that the server_name variable is correctly set if you want to run a proxy.

      6. Static files (http support)

        There is support in icecast for streaming files directory from the server to the client. This is usually handled much more nicely by a real http server, but if you don't want to go through the hassle of setting up apache or roxen or whatever, then this might be what you're looking for.
        All files must end in .mp3, and they must all be in the file tree rooted at a directory specified with the static_dir variable. This directory corresponds to the virtual directory http://server:port/file/. So a file stream.mp3 in the static_dir directory can be accessed through a http request (in a browser or mp3 player or whatever) with the url http://server:port/file/stream.mp3.

      7. Statistics

        The icecast server keeps statistics on lots of stuff when running. You can view these either by using the 'stats' command or by examining the contents of the file specified by the stats_log parameter. Icecast regularly updates this file with statistics. It can easily be parsed to produce nice output on a webpage on how many listeners are connected to your server and lots of other stuff.

      8. Access Control

        This section describes the two ways you can do access control in icecast. With access control I mean host access control, i.e a way of specifying which hosts are allowed access to the server, and which are not.

        1. Libwrap (aka tcp wrappers or tcpd)

          Libwrap is a separate library written by the well known Wietse Venema. It's a tool used all over the unix world, and is ported to all sane unix systems. It might even be available for Windows.. not sure about that :)
          Libwrap uses the files hosts.deny and hosts.allow, usually found in the /etc directory, which means that you have to be root to modify the access rules. If you are not, then skip this section and take a look at the internal acl lists.
          More information about libwrap can be found in the manpage for tcpd and hosts_access.
          You edit the hosts.allow/access file and add the icecast specific stuff, and you can do this while the icecast server is running.
          Now, what to add?
          The server "icecast" controls _all_ connections, so any host listed here will be affected, no matter what type of connection it is.
          The other servers are "icecast_admin", "icecast_client", and "icecast_source". Here the term 'server' is the first string on the line, which normally specifies the name of the binary being run, e.g in.ftpd.
          Examples:

          If you want to deny access to all clients except those with a hostmask of *.se, i.e only accept clients from sweden, then add this to hosts.deny.
          icecast_client: ALL EXCEPT *.se

        2. Internal acl lists

          Icecast offers its own access control lists. These should be used if you for some reason can't use libwrap. They are not as tested, and not as powerful as libwrap, but still quite useable.
          You can add acl lists either using the 'allow' and 'deny' command on the admin console, or by using the allow and deny parameters in the icecast.conf file.
          When none of the deny or allow rules apply to a host, then the value of the acl_policy variable decides whether the connection is allowed or not.
          Examples:
          Like the example above, you want to allow access only to clients from sweden. (this is admin console commands)
          deny add client *
          allow add client *.se

    4. Template HTML files

      Since version 1.3, icecast can now create HTML files that you can put on your website, or display to admins connecting to the icecast server with a webbrowser, accessing a specific url. The admin interface is read-only right now, you can't really change anything. For instance, try http://your.server:port/list.cgi
      To create this html-page, some other pages, along with stats.html, icecast parses a template file specified and written by the user. These template files should be in the templates directory. The syntax used in the files is pretty simple, but I suggest you take good look at the example template files shipped with icecast, and modify them.


    This document is written by Alexander Havšng [eel@musiknet.se].
    Last modified: Sat Jun 5 01:13:04 EDT 1999