<html>
<head><title>How to configure and run the icecast server</title>
</head>

<body bgcolor=black text=white link=yellow vlink=red alink=white>

<h1>Icecast Manual
<hr width=15% align=left></h1>

<p align="left">

<ol type=A>
    <li> <a href="#section_building">Building</a> 
	 <ol type=1>

	     <li> <a href="#section_download"> Downloading</a>
		  <ol type=I>
		      <li> <a href="#download_latest">Latest release</a> </li>
		      <li> <a href="#download_precompiled">Precompiled packages</a> </li>
		      <li> <a href="#download_cvs">CVS</a></li>
		      <li> <a href="#download_snapshots">Snapshots</a></li>
		  </ol>
	     </li>
	     
	     <li> <a href="#section_unpacking"> Unpacking </a> </li>

	     <li> <a href="#section_compiling"> Compiling </a>
		  <ol type=1>
		      <li> <a href="#compile_runconfigure">Running configure</a> </li>
		      <li> <a href="#compile_compiletimesettings"> Compile time settings</a> </li>
		      <li> <a href="#compile_runningmake"> Running make</a></li>
		  </ol>
	    </li>
	  </ol>
    </li>

    <li> <a href="#section_configuring"> Configuring </a>
	 <ol type=1>
	     <li> <a href="configure_commandlineoptions"> Command line options </a> </li>
	     <li> <a href="configure_configurationfile"> Configuration file (icecast.conf) </a> </li>
	 </ol>
    </li>

    <li> <a href="#section_running"> Running </a>
	 <ol type=1>

	     <li> <a href="#running_client"> Client </a>
		  <ol type=I>
		      <li> <a href="#client_windows"> Windows clients </a></li>
		      <li> <a href="#client_unix"> Unix clients </a></li>
		      <li> <a href="#client_mac"> Mac clients </a></li>
		  </ol>
	     </li>
	     
	     <li> <a href="#section_source"> Source </a>
		  <ol type=I>
		      <li> <a href="#source_shout"> Shout </a> </li>
		      <li> <a href="#source_liveice"> Liveice </a> </li>
		      <li> <a href="#source_iceplay"> Iceplay </a> </li>
		      <li> <a href="#source_winamp"> Winamp </a> </li>
								<li> <a href="#source_icesource"> Icesource </a> </li>
		  </ol>
	     </li>

	     <li> <a href="#section_admin"> Admin </a>
		  <ol type=1>
			<li> <a href="#admin_connecting"> Connecting the admin </a> </li>
			<li> <a href="#admin_commands"> Admin commands </a> </li>
			<li> <a href="#admin_settings"> Admin settings </a> </li>
	          </ol>
	     </li>
	     
	     <li> <a href="#section_directory"> Directory servers </a> </li>
	     <li> <a href="#section_relaying"> Relaying </a> </li>
	     <li> <a href="#section_static"> Static files </a> </li>
	     <li> <a href="#section_statistics"> Statistics </a> </li>
	     <li> <a href="#section_acl"> Access Control </a> </li>
	     <li> <a href="#section_templates"> Template HTML files </a> </li>
	     <li> <a href="#section_authentication"> Client Authentication Scheme </a></li>
	     <li> <a href="#section_wwwinterface"> WWW admin interface </a></li>
						<li> <a href="#section_developer"> Developers resources </a></li>
</ol>
</p>

<hr width="10%">

<p>
<ol type=A>
    <li> <a href="section_building">Building</a>
				     <p> This section describes where and how to <a href="#download">download</a>, <a href="#unpack">unpack</a> 
									    and <a href="#compile">compile</a> your icecast system.<br>
	            I suggest you read it very carefully, especially the <a href="#compile">compiling</a> chapter. 
													Installing icecast is a simple procedure, and no special magic is involved.<br>
													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.
		       </p>							
									<ol type=1>

									<li> <a name="section_download">Downloading</a>
									<p> This section describes how to get the sources, or precompiled binaries, that you need to run icecast.<br>
									    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 (<a href="#source_shout">shout</a>,
													                <a href="#source_liveice"> liveice,</a>
																													<a href="#source_winamp"> winamp,</a>
																													<a href="#source_iceplay"> iceplay,</a>
																													<a href="#source_icesource"> icesource).</a><br>
													Some, like shout is usually included in the icecast packages. Others you'll have to download separately.
									</p>

  				<ol type=I>

					<li> <a name="download_latest">Latest release</a>
						<p> 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.0. 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 :)<br>
						    To get the latest release, go to <a href="http://www.icecast.org">www.icecast.org</a> and click on downloads.
						</p>
					</li>

					<li> <a name="download_precompiled">Precompiled packages</a>
						<p> 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 2.0, 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 :)<br>
						    You get the precompiled binaries at <a href="http://www.icecast.org">www.icecast.org</a>, click on downloads.
						</p>
					</li>

		    <li> <a name="download_cvs">CVS (the cutting edge)</a>
						<p> 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 :)<br>
						    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).<br>
						    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 <a href="http://www.cyclic.com/">www.cyclic.com</a> and follow this 
										procedure:<br>
						    export CVSROOT='anonymous@cvs.icecast.org:/cvsroot'<br>
						    cvs login<br>
						    There is no password, just press enter.<br>
						    cvs -z3 checkout icecast<br>
						    And your done. Please note cvs sources are not stable, they change all the time and therefore might not 
										build, or the server might crash. Also, you might note that there is no configure script, you need to use 
										the ./autogen.sh script, that in runs automake, autoconf, configure and some other stuff.<br>
					     To keep an eye on icecast development, you can go to <a href="http://cvs.icecast.org/">cvs.icecast.org</a> 
										and browse through the files, see the differences between the different versions, see what has been 
										updated lately, and who's doing what.<br>
					     If you want a cross referenced html version of the whole icecast sourcetree,
					     go to <a href="http://source.icecast.org/">source.icecast.org</a>.<br>
						</p>
					</li>
	
					<li> <a name="download_snapshots">Snapshots</a>
						<p> For those of you who don't want to, or for some reason can't, use the cvs system, snapshots of the cvs 
						    modules are created once a day. Go to <a href="http://snapshots.icecast.org/">snapshots.icecast.org</a>, 
										and download the latest snapshot. The snapshots should have the configure script already set up for you.<br>
					</p>
					</li>
	  			</ol>	    
			</li>

			<li> <a name="section_unpacking">Unpacking </a>
				<p> 	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-<version>.tar.gz.<br>
					    If you've downloaded a precompiled package, then you hopefully know how to install it yourself :)<br>
				</p>
			</li>
	
			<li> <a name="section_compiling">Compiling</a>
				<p> This section describes how to compile the icecast system. Step by step instructions, and what options you 
				    have.<br>
				    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.
				</p>
				
	   			<ol type=I> 
	    				<li> <a name="compile_runconfigure">Creating the Makefile with configure</a>
						<p> In the toplevel icecast directory, there should be a file called configure.<br>
						    If there is not, but there is a file called ./autogen.sh, use this instead of ./configure.<br> 
						    The configure script creates the Makefile. If you want the default setup, just run it with ./configure.<br>
						    There are three options to the configure script that you might want to enable.<br>

					        <p>
					            The first is --with-libwrap, which enables support for Wietse Venema's tcp wrappers. 
																	See the section about <a href="#section_acl">access control</a> below.
												</p>
						       <p>
					            The second is --with-crypt, which means that the passwords you specify in icecast.conf, users.aut
																	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.
					        </p>
													
													<p>
													    The third is --without-readline, which means that readline support, even if found, will not be used. 
													    You will not be able to use tab completion or command line editing on the icecast console.
					        </p>
						
												No other options to the configure script make any difference.
					 </p>

	    				<li> <a name="compile_compiletimesettings">Compile time settings </a>
									     <p> This section describes what you can change in the Makefile, icetypes.h and icecast.h to 
														    optimize performance and change the default behavior of the icecast system. You do <b>not</b> 
																		have to go through this step if you just want the default setup.<br>
																		This step is optional.<br>
													 </p>
						<ol type=I>
							<li> Editing the Makefile
								<p> 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.<br>
								    The first two lines describe the compile being used (CC), and the compiler flags (CFLAGS). Change these
								    to whatever is best on your system.<br>
								    For example, I use CC=gcc and CFLAGS= -O5 -march=i686 -mcpu=i686 -fstrict-aliasing.<br>
								</p>
							</li>
							<li> Editing icetypes.h
								<p>
							             The one single most important compile time setting for the icecast server is SOURCE_BUFFSIZE.<br>
							             It sets how many bytes will be read from the source before trying to send this chunk to the
							             clients. It is by default set to 4096, because not all systems can read more than 4096 bytes in
							             a single system call. If your server will take on a lot of listeners, or stream very high
							             bitrate mpeg data, like video system mpeg streams, and if you system supports it, you should
							             increase this value to 64 KiB or something similar.<br>
																				If you want a larger backlog for each client, which will allow for worse network congestion or 
																				other network errors before kicking the client, increase the CHUNKLEN value.<br>
								</p>
						 </li>	 
							<li> Editing icecast.h
							     <p>
								Depending on which version of icecast you've got, there might be some extra defines you 
								can set in icecast.h. For the 1.3.6 release, these are OPTIMIZE, SAVE_CPU, and some
								defines that only affect debugging.<br>
								SAVE_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.<br>
								OPTIMIZE 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.<br>
								Combined, SAVE_CPU and OPTIMIZE might decrease cpu usage with up to 75%.<br>
								DEBUG_MEMORY_MCHECK will (if mcheck.h is available) turn on malloc debugging. Probably only
								useful for developers.<br>
								DEBUG_MUTEXES will turn on a lot of extra tracing and debugging for mutex locks. It will tell
								you when the server locks mutexes in a way that might deadlock the server, and lots of other
								stuff. This also, is only useful for developers.<br>
								DEBUG_SOCKETS will activate the 'sock' command on the icecast console, which enables the
								user to list all open sockets, and close them if necessary. This can be kind of neat when a
								source is stuck in i/o and refuses to die. Closing the socket kills him for sure :)<br>
								DEBUG_FULL will turn on <b>all</b> debugging and you can't turn it off again, it is turned on long
								before the command line or configfiles are parsed and is used to find errors early in the
								initialization phase.<br>
							        </p>
							</li>
						</ol>
	   </li>

					<li> <a name="compile_runningmake">Compiling (running Make)</a>
						<p> Now it's time to run make. icecast has been developed using gnu make, and even if other makes might work,
						    I would recommend using GNU Make.<br>
						    Type 'make' (or 'gmake'), and off we go. This will compile the icecast server.<br>
						    If you want the other icecast related tools, you'll have to download and install them separately.<br>
						    If you get <b>any</b> errors or warnings while compiling icecast, you should notify devel@icecast.org. 
						    We want the compilation procedure to be 100% clean on all platforms.<br>
						    Now type 'make install' (or 'gmake install'), and icecast will be installed. If you don't install icecast, 
										it will probably not find the configuration files, templates, authorization files, 
										but it will still work.<br>
						</p>
					</li>
				</ol>
			</li>
		</ol>
  	</li>	
  	<li> <a name="section_configuring"> Configuring </a>
		<ol type=1>
			<li> <a name="configure_commandlineoptions"> Command line options </a>
				<p> The following command line parameters can be given when you start the icecast server.<br>
				    Command line parameters override all configuration file parameters (icecast.conf), which in 
								turn override the default compile time settings.
				</p>
				<ul>
					<li> -c [filename]
						<p> Parse <filename> 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>
					</li>
					<li> -P [port]
						<p> This is the port used for all client, source, and admin connections. It's set to 8000 by default.
						</p>
					</li>
					<li> -m [max clients]
						<p> 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>
					</li>
					<li> -p [encoder password]
						<p> 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.
						</p>
					</li>
					<li> -b
						<p> 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.
						</p>
					</li>
					<li> -d [directory]
						<p> Specifies the directory where icecast will look for configuration and authorization files.
						</p>
					</li>
					<li> -V
						<p> Turn on full debugging.
						</p>
				        </li>
				</ul>
			</li>
			<li> <a name="configure_configurationfile"> Configuration file (icecast.conf) </a>
				<p> This section describes the configuration parameters inside icecast main configuration file, icecast.conf.
				    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.<br>
				    Configuration parameters are specified as 'parametername parameter', where parametername is a string 
								without spaces and parameter is the rest of the line.<br>
								Never enclose the parameter in double quotes ("").<br>
								Most of these parameters can be changed using the <a href="#command_set">set</a> command on the 
								admin console.<br>
				</p>
				<ul>
					<li> <a name="set_encoder_password">encoder_password</a>
						<p> This is the password by which the server accepts encoders, metadata connections and pushing relays.<br>
						    You cannot connect to the server as an admin with this password.<br>
						</p>
					</li>

					<li> <a name="set_admin_password">admin_password</a>
						<p> The password needed for admins to be accepted to the admin console. Access to the WWW admin interface does
						    not use this password, see the section about the <a href="#section_wwwinterface">WWW interface</a> 
										below.</p>
					</li>

					<li> <a name="set_oper_password">oper_password</a>
						<p> This is the password an admin must specify to get access to the restricted server operator commands.</p>
					</li>

					<li> <a name="set_touch_freq">touch_freq</a>
						<p> This setting regulates how often the directory servers get 'touched' by the icecast server.<br>
						    The default setting of 5 minutes is a good value.
						</p>
					</li>

					<li> <a name="set_max_clients">max_clients</a>
						<p> The maximum number of simultaneous clients connected to the server. </p>
					</li>

					<li> <a name="set_max_sources">max_sources</a>
						<p> Max. number of simultaneous sources connected to the server. </p>
					</li>

					<li> <a name="set_max_admins">max_admins</a>
						<p> Max. number of simultaneous connected admins. WWW admins are not affected since they are not 
						    interactively logged on.
						</p>
					</li>

					<li> <a name="set_logfile">logfile</a>
						<p> This file, icecast.log in /usr/local/icecast/log by default, is the icecast server's main logfile.<br>
						    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. If it grows 
										way to big, and you want to truncate it yourself, without restarting icecast, then you have to send 
										icecast the SIGHUP signal so that it reopens the logfile.<br>
										This means you can use common logrotating programs.<br>
						</p>
					</li>

					<li> <a name="set_hostname">hostname</a>
						<p> 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 adress, then icecast will 
										<b>only</b> listen on that IP adress. 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.
						</p>
					</li>

					<li> <a name="set_server_name">server_name</a>
						<p> 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. See also the <a href="#set_force_servername">force_servername</a> setting.<br>
										When using <a href="#section_relaying">aliases</a> and in some cases multiple mountpoints, 
										client have to request streams from this servername, otherwize they will not get the correct stream.<br>
										For those of you familiar with virtual hosts in webservers, this is something similar :)
						</p>
					</li>

					<li> <a name="set_console_mode">console_mode</a>
						<p> This sets how the icecast server is started, and what the tty you started icecast in will be used for.<br>
						    0 means use it as a admin console (you can send commands to the icecast server) with logfile info.<br>
						    1 is the same as 0 but without logfile info.<br>
						    2 means just use it as a logfile window.<br>
						    3 means put the icecast server in the background, as a daemon process. <br>
						    All console modes are not available on all platforms.<br>
						</p>
					</li>

					<li> <a name="set_client_timeout">client_timeout</a>
						<p> 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.
						</p>
					</li>

					<li> <a name="set_stats_log">stats_log</a>
						<p> The icecast server dumps statistics to a file on a regular basis. See the section about 
						    <a href="#section_statistics"> statistics</a> below.<br>
						    This sets what file is used for statistics.
						</p>
					</li>

					<li> <a name="set_statshtml_log">statshtml_log</a>
					    <p> This works just like stats_log, but the statistics are html-formatted, 
									    using the statistics.html template.
					    </p>
					</li>

					<li> <a name="set_stats_time">stats_time</a>
					    <p> This setting, in seconds, sets how often the statistics files get updated.</p>
					</li>

					<li> <a name="set_max_clients_per_source">max_clients_per_source</a>
					    <p> The maximum number of simultaneous clients connected to the same stream on the server. 
									    Setting this to a value larger than max_clients does not make any sense.
					    </p>
					</li>
					    
					<li> <a name="set_reverse_lookups">reverse_lookups</a>
						<p> 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.
						</p>
					</li>

					<li> <a name="set_location">location</a>
						<p> 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.<br>
						    No syntactic controls apply, but if you want to follow the standard, 
										use 'STATE, COUNTRY', or 'CITY, COUNTRY'.
						</p>
					</li>

					<li> <a name="set_rp_email">rp_email</a>
						<p> This should be set to the email adress of the admin running the server.</p>
					</li>

					<li> <a name="set_transparent_proxy">transparent_proxy</a>
						<p> 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 
										<a href="#section_proxies">proxies</a> below.
						</p>
					</li>

					<li> <a name="set_acl_policy">acl_policy</a>
						<p> This regulates whether connections are allowed or denied if no acl rule exists that affects them. 
						    See the section about <a href="#section_acl">Access Control</a> below.<br>
										Setting it to 0 will deny all these connections, and 1 will allow them.
						</p>
					</li>

					<li> <a name="set_throttle">throttle</a>
					    <p> 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.
					    <p>
					</li>

					<li> <a name="set_kick_relays">kick_relays</a>
						<p> 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.
						</p>
					</li>

					<li> <a name="set_kick_clients">kick_clients</a>
						<p> 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.
						</p>
					</li>

					<li> <a name="set_status_time">status_time</a>
					    <p> This setting regulates how often status information is printed on the admin console.</p>
					</li>

					<li> <a name="set_staticdir">staticdir</a>
						<p> 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 
										<a href="#section_static">Static files</a> below.<br>
						    This sets what directory on disk will be the root for http://your.server.com:port/file/
						</p>
					</li>

					<li> <a name="set_logfiledebuglevel">logfiledebuglevel</a>
						<p> 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 :). 6 is the current maximum.
						</p>
					</li>

					<li> <a name="set_consoledebuglevel">consoledebuglevel</a>
						<p> This is the same as logfiledebuglevel, but regulates the output on the icecast console </p>
					</li>
					    
					<li> <a name="set_server_url">server_url</a>
					    <p> This should be set to a URL describing this icecast server.</p>
					</li>

					<li> <a name="set_use_meta_data">use_meta_data</a>
					    <p> This will enable title streaming the way shoutcast does it. This is old, stupid and will probably
					        mess up your stream. Turn this off unless you really want it.<br>
					    </p>
					</li>
					    
					<li> <a name="set_streamurl">streamurl</a>
										<p> If the sources don't set a url for the stream, then this variable is the default url for titlestreaming.
										</p>
					</li>
					    
					<li> <a name="set_streamurllock">streamurllock</a>
					     <p> If you don't want the sources to be able to change the url of their streams, set this to 1. </p>
					</li>
					    
					<li> <a name="set_streamtitletemplate">streamtitletemplate</a>
					     <p> 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.
					     </p> 
				        </li>
					    
					<li> <a name="set_nametemplate">nametemplate</a>
					     <p> 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.
					     </p>
					</li>
					    
					<li> <a name="set_desctemplate">desctemplate</a>
					     <p> 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.
					     </p>
					</li>
					
					<li> <a name="set_accessfile">accessfile</a>
										<p> This file logs all the client connections to the server and should be parsable with any common logfile
										    parser. It uses the same format as apache and other webservers.
										</p>
     </li>

					<li> <a name="set_usagefile">usagefile</a>
										<p> This file is periodically updated with server usage information.
										</p>
					</li>

					<li> <a name="set_default_source_options">default_source_options</a>
										<p> This string is the default options for the <a href="#command_sources">'sources'</a> command.
										</p>
					</li>

					<li> <a name="set_mount_fallback">mount_fallback</a>
					    <p> Normally users who request a stream that is not found, they will get the default stream instead. 
									    When this is set to 0 they will get a HTTP 404 Stream Not Found instead.
					    </p>
					</li>
			
					<li> <a name="set_force_servername">force_servername</a>
										<p> The directory server will use the originating ip of the icecast server unless this is set to 1. 
										    If set to 1, this will make the directory server use the server_name variable instead. This is 
														useful for people behind transparent proxies.
					    </p>
					</li>

					<li> <a name="set_logdir">logdir</a>
										<p> This is the directory wherein logfiles are kept.
										</p>
					</li>

					<li> <a name="set_templatedir">templatedir</a>
										<p> This is the directory where icecast looks for templates for the WWW admin and generation of stats.html.
										</p>
					</li>

					<li> <a name="set_resolv_type">resolv_type</a>
										<p> This variable regulates what kind of resolving functions icecast uses. Setting it to 1 means it will 
										    use linux reentrant interface (gethostbyname_r()), 2 means solaris reentrant interface, 
														and 3 is the standard nonreentrant interface.
										</p>
					</li>

					<li> <a name="set_http_admin">http_admin</a>
										<p> This setting regulates whether to allow access to the WWW interface at all. 1 means yes, 0 means no.
										</p>
					</li>

					<li> <a name="set_relay_reconnect_max">relay_reconnect_max</a>
										<p> This variable regulates how many times icecast will try to reconnect a relay. -1 means infinite times.
										</p>
					</li>

					<li> <a name="set_relay_reconnect_time">relay_reconnect_time</a>
										<p> This regulates how many seconds to wait between relay reconnect tries.
										</p>
					</li>

					<li> <a name="set_sleep_ratio">sleep_ratio</a>
										<p> This is a float variable that regulates how long a source thread in the server sleep between reading
										    from the encoder. Setting it to a very low value will make the system use a little more cpu, and it
														might behave a little flaky with few listeners. Setting it to a very high value will probably make
														the audio very choppy. I.e few listeners, use a larger value, and with lots of listeners, use a
														smaller value. Anything larger than 1.0 and smaller than 0.0 is just pointless.<br>
														Also, a fast cpu will be able to use a higher value than a slow cpu.<br>
										</p>
					</li>

					<li> <a name="set_directory">directory</a>
						<p> 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'<br>
							   Please note that this is the syntax for xaudiocast directory	server. Some old directory servers use
										the old icy headers. If you want that, use the <a href="#set_icydir">icydir</a> command.<br>
						</p>
					</li>

					<li> <a name="set_icydir">icydir</a>
						<p> This adds a icy directory server (such as yp.shoutcast.com). 
						    The syntax is simply 'icydir directory.host.domain'.
						</p>
					</li>

					<li> <a name="set_port">port</a>
						<p> 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.<br>
										You can now use multiple ports, just add another port line.<br>
										port 8000<br>
										port 8001<br>
										The above will make icecast listen on 8000 and 8001.<br>
						</p>
					</li>

					<li> <a name="set_alias">alias</a>
						<p> 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.<br> 
										'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.
						</p>
					</li>
						
					<li> <a name="set_allow">allow</a>
						<p> This adds a hostmask for a specific type connection, which will be allowed access. 
						    Syntax is 'allow [type] [hostmask]'.<br>
						    See the section below on Access Control.
						</p>
					</li>

					<li> <a name="set_deny">deny</a>
						<p> This adds a hostmask for a specifi type connection, which will be refused access.<br>
						    Syntax is 'deny [type] [hostmask]'.<br>
						</p>
					</li>

					<li> <a name="set_relay">relay</a>
									 <p> This works just like the <a href="#command_relay">relay</a> pull command. Icecast will connect
														this relay at boot time, and reconnect it if it disconnects.
										</p>
					</li>
					
					<li> <a name="set_include">include</a>
										<p> This will parse another configfile.<br>
														Ex: include /etc/defaulticecast.conf<br>
										</p>
					</li>

				</ul>
			</li>		
		</ol>
  	</li>

  	<li> <a name="section_running"> Running </a>
		<p> 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...
		</p>
		<ol type=1>

			<li> <a name="running_client"> Client </a>
				<p> 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.
				</p>
				<ol type=I>
					<li> <a name="client_running"> Windows clients </a>
						<ul>
						  <li> <a href="http://www.sonique.com/"> Sonique </a>
						      <p> A very cool client for windows. People say its even more stable than winamp when it comes to 
												    streaming. And it looks damn cool :)<br>
																Sonique supports xaudiocast titlestreaming.<br>
						      </p>
						  </li>

						  <li> <a href="http://www.kjofol.com/"> K-Jofol </a>
						      <p> Another really cool client, based on the mpg123 engine.</p>
						  </li>

						  <li> <a href="http://www.winamp.com/"> Winamp </a>
						      <p> 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, or titlestreaming, and probably never will.
						      </p>
						  </li>
						      
						</ul>
					</li>
					<li> <a name="client_unix"> Unix clients </a>
						<ul>
							<li> <a href="http://www.xmms.org/"> XMMS (formerly x11amp) </a>
								<p> 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.
								</p>
							</li>
					
							<li> <a href="http://mpg.123.org/"> mpg123 </a>
								<p> Perhaps the most widely used mp3 player for unix. Command line driven, and with some limited support
								    for audiocast streaming.
								</p>
							</li>

							<li> <a href="http://www.freeamp.org"> FreeAmp </a>
								<p> Getting more stable with every release, FreeAMP is also an option in the unix world. 
								</p>
							</li>
						</ul>
					</li>
					<li> <a name="client_mac"> Mac clients </a>
					    <ul>
					      <li> <a href="http://www.macamp.net/">MacAST</a> </li>
											<li>	<a href="http://www.soundjam.com/">SoundJam</a></li>
									</ul>
					</li>
				</ol>
			</li>
			<li> <a name="section_source"> Source </a>
				<p> 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.<br>
				    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.<br>
				    Static streaming requires almost no amount of cpu or memory resources.<br>
				    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.<br>
				</p>
			    <ol type=I>
			        <li> <a name="source_shout"> shout </a>
					<p> Shout is a static file streamer with a powerful playlist engine and a finely tuned transfer loop.<br>
					    It has a large number of command line and configuration file parameters. 
					    Shout supports the new x-audiocast headers and is bundled with the icecast package. It supports 
									titlestreaming of id3 tags and filename.<br>
									Shout development has now stopped, and we've started over on a new streamer, called icesource. Complaints
									and bugreports for shout will be redirected to the large and hungry alligator hiding in /dev/null.
					</p>
				</li>
				<li> <a name="source_liveice"> liveice </a>
					<p> 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.<br>
					    For more info about liveice, including download location, go to the 
									<a href="http://star.arm.ac.uk/~spm/software/liveice.html">liveice</a> webpage.
					</p>
				<li> <a name="source_iceplay"> iceplay </a>
					<p> iceplay is the ancient icecast pre 1.0 streamer. It's a static file streamer written in perl.
					</p>
				</li>
				<li> <a name="source_winamp"> winamp </a>
					<p> winamp is both a client and a streamer for Windows. It's a re-encoding streamer.
					</p>
				</li>
				<li> <a name="source_icesource"> icesource </a>
				 <p>	icesource is the new main icecast streamer. It's under development and not yet ready for the big masses.<br>
					    it uses the new source development library libshout.
					</p>
				</li>
			</ol>
			</li>
			<li> <a name="section_admin"> Admin </a>
				<p> This section describes the admin console, how to connect and what commands are available.
				</p>
				<ol type=I>
					<li> <a name="admin_connect"> Connecting the admin </a>
						<p> 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.<br>
					     When you connect, nothing will be printed, no prompt, nothing. Then you type the following:<br>
						    '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.
						</p>
					<li> <a name="admin_commands"> Commands </a>
						<p> The following commands are available in the icecast admin console. Most of them requires icecast operator 
						    access. To become an icecast operator, use the <a href="#oper">oper</a> command with the operator password 
										as an argument.
						</p>
						<ul>
							<li><a name="command_alias"> alias </a>
								<p> 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 <a href="#section_relaying">relaying</a> using aliases below.<br>
								    Syntax:<br>
								    <tt>
								    	alias add &lt;mountpoint&gt; &lt;newmountpoint&gt;<br>
								    	alias del &lt;mountpoint&gt;<br>
								    	alias list<br>
								    </tt>

								    <b> New in 1.3.8</b> is the "whatever" keyword. If you specify the string 'whatever', without quotes of course, as the host of an alias, then it will match <b>all</a> hosts. This is useful for building generic aliases for certain mountpoints.<br>

								    Examples:<br>
								    <tt> 
													alias add /icy_0 /coolstream<br>
													alias add /radiofri http://195.7.65.207:6903/ <br>
													alias add http://whatever/crappyfunk http://crappyfunk.com:8000/funk
													
								    </tt>
								</p>
							</li>
	
							<li> <a name="command_allow">allow</a> and <a name="command_deny">deny</a>
								<p> 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.<br>
												Also see the section about <a href="#section_acl">access control</a> below.<br>
								    Syntax:<br>
								    <tt>
								    	allow|deny &lt;client|source|admin|all&gt; add &lt;hostmask&gt;<br>
								    	allow|deny &lt;client|source|admin|all&gt; del &lt;hostmask&gt;<br>
								    	allow|deny &lt;client|source|admin|all&gt; list<br>
								    </tt>
								    Examples:<br>
												<tt>
								    		allow client add *.se<br>
								    		allow all del *.netcom.com<br>
														deny admin add *.se<br>
														deny admin del ap.*.com<br>
								    		allow admin list<br>
												</tt>
								</p>
							</li>

							<li> <a name="command_admins">admins</a>
								<p> 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:<br>
												<tt>
												Admin 341       &lt;d66.ryd.student.liu.se&gt; connected for 1 hours, 8 minutes and 14 seconds. 
												0 commands issued<br>
												</tt>
								    You can supply a hostmask as an argument, and then you will only get the admins who match the mask.<br>
								    Syntax:<br>
												<tt>
														admins [hostmask]<br>	
												</tt>
												Examples:<br>
												<tt>
														admins *.icecast.org<br>
												</tt>
								</p>
							</li>
					
							<li> <a name="command_dir">dir</a>
								<p> 	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.<br>
													Syntax:<br>
													<tt>
													dir add &lt;host[:port[/path/to/program]]&gt; [icy]<br>
													dir del &lt;host&gt;<br>
													dir list<br>
													</tt>
													Examples:<br>
													<tt>
													dir add yp.shoutcast.com icy<br>
													dir add yp.icecast.org<br>
													dir list<br>
													dir del yp.icecast.org<br>
													</tt>
								</p>
							</li>
			
							<li> <a name="command_dump">dump</a>
								<p> 	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 :)<br>
								    	If the filename specified is 'close', then the file will be closed.<br>
								    	Syntax:<br>
													<tt>
													dump &lt;source id&gt; &lt;filename|close&gt;<br>
													</tt>
													Examples:<br>
													<tt>
													dump 230 /tmp/stream.mp3<br>
													</tt>
								</p>
							</li>
							
							<li> <a name="command_help">help</a>
								<p>	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.<br>
											 Syntax:<br>
												<tt>
												  help [command]<br>
												</tt>
												Examples:<br>
												<tt>
												  help kick<br>
														help<br>
												</tt>
								</p>									
							</li>
							
							<li> <a name="command_kick">kick</a>
								<p>	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.<br>
									Syntax:<br>
									<tt>
										kick &lt;id&gt;<br>
										kick &lt;-acs&gt; &lt;hostmask&gt;<br>
										kick &lt;hostmask&gt;<br>
									</tt>
									Examples:<br>
									<tt>
										kick 314<br>
										kick -a *.com<br>
										kick *.nullsoft.com<br>
									</tt>
								</p>
							</li>
							
							<li> <a name="command_listeners">listeners</a>
								<p>	When you want to list all connected listeners, 'listeners' is the command you are looking for.<br>
									You can list all, or those matching a hostmask.<br>
									Syntax:<br>
									<tt>
										listeners [hostmask]<br>
									</tt>
									Examples:<br>
									<tt>
										listeners *.frobnication.frob.org<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_modify">modify</a>
								<p>	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.<br>
									-m means mountpoint, -u means url, -n means name, -d means description, -g means genre, 
									-p means public, -b means bitrate and -P priority<br>
							  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.<br>
									Syntax:<br>
									<tt>
										modify &lt;source id&gt; &lt;-mungdpb&gt; &lt;new value&gt;<br>
									</tt>
									Examples:<br>
									<tt>
										modify 23 -d The bluest blues you've ever heard<br>
										modify 54 -m /coolblues<br>
									</tt>
								</p>
							</li>
							
							<li> <a name="command_oper">oper</a>
								<p>	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.<br>
									Syntax:<br>
									<tt>
										oper &lt;operator password&gt;<br>
									</tt>
									Examples:<br>
									<tt>
										oper cooloperpass<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_pause">pause</a>
								<p>	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. <br>
									Syntax:<br>
									<tt>
										pause &lt;client or source id&gt;<br>
									</tt>
									Examples:<br>
									<tt>
										pause 314<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_quit">quit</a>
								<p>	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.<br>
									Syntax:<br>
									<tt>
										quit [message]<br>
									</tt>
									Examples:<br>
									<tt>
										quit Bye Bye<br>										      
									</tt>
								</p>
							</li>

							<li> <a name="command_rehash">rehash</a>
								<p>	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.<br>
									Syntax:<br>	
									<tt>
										rehash [filename]<br>
									</tt>
									Examples:<br>
									<tt>
										rehash /tmp/newicecast.conf<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_select">select</a>
								<p>	'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.<br>
									Syntax:<br>
									<tt>
										select &lt;-a&gt; &lt;source source id&gt; &lt;target source id&gt;<br>
										select &lt;client id&gt; &lt;target source id&gt;<br>
										select &lt;source source id&gt; &lt;hostmask&gt; &lt;target source id&gt;<br>
									</tt>
									Examples:<br>
									<tt>
										select 514 23<br>
										select -a 43 23<br>
										select 23 *.se 43<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_sources"> sources </a>
								<p>	'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. It also accepts a large
							                number of options. By default the output is defined by the variable default_sourceopts.<br>
							                The options are as follows.
							                <ul>
									  <li>i - Connection id</li>
									  <li>s - Socket descriptor</li>
									  <li>t - Time of connect</li>
									  <li>p - Connection ip</li>
									  <li>h - Hostname</li>
									  <li>c - Connection state</li>
									  <li>y - Source type</li>
									  <li>o - Protocol</li>
									  <li>c - Number of clients</li>
									  <li>d - Dumpfile</li>
									  <li>r - Mountpoint priority</li>
									  <li>l - Song title</li>
									  <li>u - Song url</li>
									  <li>m - Stream message</li>
									  <li>n - Song length</li>
									  <li>a - Source name</li>
									  <li>g - Source genre</li>
									  <li>b - Source bitrate</li>
									  <li>U - Source URL</li>
									  <li>M - Source mountpoint </li>
									  <li>D - Source description </li>
									  <li>R - Bytes read</li>
									  <li>W - Show bytes written</li>
									  <li>C - Total client connects</li>
									  <li>T - Time connected</li>
									</ul>
									
									Syntax:<br>
									<tt>
										sources [hostmask] [-options]<br>
									</tt>
									Examples:<br>
									<tt>
										sources *.apan.com -aCW <br>
									</tt>
								</p>
							</li>

							<li> <a name="command_shutdown">shutdown</a>
								<p>	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.<br>
									Syntax:<br>
									<tt>
										shutdown [message]<br>
									</tt>
									Examples:<br>
									<tt>
										shutdown Oh shit, oh shit, OH SHIT!<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_set">set </a>
								<p>	 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. Typing 'help settings' will give you a short description of all the settings, and
							   a longer description for the settings is available <a href="#configure_configurationfile">here</a>.<br>
									 Syntax:<br>
									 <tt>
										set<br>
										set &lt;variable name&gt;<br>
										set &lt;variable name&gt; &lt;new value&gt;<br>
									</tt>
									Examples:<br>
									<tt>
										set client_timeout<br>
										set max_clients 580<br>
									</tt>
								</p>
							</li> 
							
							<li> <a name="command_stats">stats</a>
								<p>	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.<br>
									Syntax:<br>
									<tt>
										stats [hourly|daily]<br>
									</tt>
									Examples:<br>
									<tt>
										stats hourly<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_tail">tail</a>
								<p>	The 'tail' command can be issued by an admin to intercept messages written to the logfile.<br>
									It's similar to the unix tail command.<br>
									Syntax:<br>
									<tt>
										tail<br>
									</tt>
									Examples:<br>
									<tt>
										tail<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_tell">tell</a>
								<p>	An admin can send a message to all other connected admins using the 'tell' command. Any arguments
									will get printed to all admins.<br>
									Syntax:<br>
									<tt>
										tell &lt;message&gt;<br>
									</tt>
									Examples:<br>
									<tt>
										tell This song really rox!<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_touch">touch</a>
								<p>	You can use the 'touch' command to force the icecast server to immediately touch all directory
									servers.<br>
									Syntax:<br>
									<tt>
										touch<br>
									</tt>
									Examples:<br>
									<tt>
										touch<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_unpause">unpause</a>
								<p>	The 'unpause' commands unfreezes a client or stream previously paused with the 'pause' command.<br>
									Syntax:<br>
									<tt>
										unpause &lt;client or source id&gt;<br>
									</tt>
									Examples:<br>
									<tt>
										unpause 314<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_uptime">uptime</a>
								<p>	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.<br>
									Syntax:<br>
									<tt>
										uptime<br>
									</tt>
									Examples:<br>
									<tt>
										uptime<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_list">list</a>
								<p>	To list all connections. All sources, admins, and clients, then you should use the 'list' command.<br>
									Syntax:<br>
									<tt>
										list [hostmask]<br>
									</tt>
									Examples:<br>
									<tt>
										list *.toomanyarguments.com<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_relay">relay</a>
								<p>	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 <a href="#section_relaying">relaying</a> 
									below.<br>
									Syntax:<br>
									<tt>
										relay push &lt;source id&gt; &lt;host[:port]&gt; [options]<br><br>
										</tt>
											Where options are:<br>
											      -p &lt;password&gt;<br>
											      -u &lt;url&gt;<br>
											      -m &lt;mountpoint&gt;<br>
											      -n &lt;name&gt;<br>
											      -g &lt;genre&gt;<br>
											      -P &lt;public&gt;<br>
											      -b &lt;bitrate&gt;<br>
											      -d &lt;description&gt;<br>
											      -i (means remote server is an icy server)<br>
										<tt><br>
											relay pull [-m &lt;localmount&gt;] &lt;url&gt;<br>
									</tt><br>
									Examples:<br>
									<tt>
										relay push 314 ice.berg.org:7343 -p 3l33t -u www.icecast.org<br>
										relay pull http://reall.y.co.ol:45500/cool<br>
									</tt>
								</p>
							</li>

							<li> <a name="command_threads">threads</a>
								<p>	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.<br>
								</p>
							</li>

							<li> <a name="command_locks">locks</a>
								<p>	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.<br>
								</p>
							</li>

							<li> <a name="command_status">status</a>
								<p>	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.<br>
									Syntax:<br>
									<tt>
										status [off|on]<br>
									</tt>
									Examples:<br>
									<tt>
										status off<br>
									</tt>
								</p>
							</li>

						<li> <a name="command_mem">mem</a>
							<p>  The 'mem' command shows current memory usage (if available). It can also be used to turn memory
							     tracing on and off. This is of course only useful for debugging.<br>
												Syntax:<br>
												<tt>
												 mem [trace|untrace]<br>
												</tt>
												Examples:<br>
												<tt>
												  mem trace<br>
														mem<br>
												</tt>
						 </p>
					 </li>
							
							<li> <a name="command_streamtitle">streamtitle</a> and <a name="command_streamurl">streamurl</a>
							     <p> These commands are used to change the title and url in the titlestreaming for a given stream.<br>
												    Use the -a option to change all streams.<br>
																Syntax:<br>
																<tt>
																streamtitle [-a|sourceid] [new title]<br>
																streamurl   [-a|sourceid] [new url]<br>
																</tt>
																Examples:<br>
																<tt>
																streamtitle -a "Hey o Hey, this is your captain speaking"<br>
																streamurl   -a "http://www.thisisnotporn.com/"<br>
																</tt>
												</p>
						</li>

						<li> <a name="command_describe">describe</a>
						     <p> This command is used to display detailed information about a connection.<br>
											    Syntax:<br>
															<tt>
															describe [id]<br>
															</tt>
															Examples:<br>
															<tt>
															describe 23<br>
															</tt>
											</p>
						</li>

						<li> <a name="command_auth">auth</a>
						     <p> This command is used to display authorization users, mounts and groups. See the section
											    about <a href="#section_authorization">authorization below.<br>
															Syntax:<br>
															<tt>
															auth &lt;groups|users|mounts&gt;<br>
															</tt>
															Examples:<br>
															<tt>
															auth groups<br>
															auth users<br>
															</tt>
											</p>
							</li>
							
							<li> <a name="command_server_info">server_info</a>
							     <p> The 'server_info' command displays information on this binary and system limits. For instance
												    compile time settings and the maximum number of threads.<br>
																Syntax:<br>
																<tt>
																server_info<br>
																</tt>
																Examples:<br>
																<tt>
																server_info<br>
																</tt>
												</p>
							</li>
																
							<li> <a name="command_debug">debug</a>
								<p>	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 6 is the current max.<br>
									Syntax:<br>
									<tt>
										debug [digit]<br>
									</tt>
									Examples:<br>
									<tt>
										debug 3<br>
									</tt>
								</p>
							</li>
						</ul>
					</li>
				</ol>
			</li>

			<li> <a name="section_directory"> Directory servers </a>
			     <p> This section talks about directory services, what they are and what they provide and the difference 
								    between them.
			     </p>
			     <ol type=I>
				 <li> What is a directory server?
				      <p>     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.<br>
																		Newer directory servers use the xaudiocast protocol, with support for multiple streams and 
																		relay lists. Older directory servers (like yp.shoutcast.com) still use a one-stream-per-server
																		protocol and from time to time yp.shoutcast.com even come up with stupid new ideas that shut
																		icecast servers out. There are always ways around this of course :)<br>
				      </p>
				 </li>
				 <li> How do I make my icecast server talk to a directory server?
				      <p> 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 <a href="#command_dir">command</a>, 
														or add them in the configuration file with the <a href="#set_dir">'dir'</a> and 
														<a href="#set_icydir">'icydir'</a> paramaters.<br>
				      </p>
				 </li>
			     </ol>
			</li>      
				      
			<li> <a name="section_relaying"> Relaying </a>
				<p>	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.<br>
								Not to mention that the network administrators will nuke my swedish arse if they found out :)<br>
								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 ;)<br>
								There are three types of relays in the icecast server. Pushing, pulling, and aliased relays 
								(aka on demand relays)<br>
								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.<br>
								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.<br>
								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.<br>
				</p>

				<ol type=I>
					<li> Pulling relays
						     <p> 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.<br>
						     </p>
					</li>
						     
					<li> Pushing relays
					     <p> 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.<br>
					     </p>
					</li>

					<li> Relaying using aliases
					     <p> Aliases for remote streams are added with the 'alias add' command or using the alias parameter in the 
										icecast.conf file.<br>
										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.<br>
Prior to the 1.3.8 release, the requested stream URL had to match the alias
exactly, using the server_name as the host part of the URL. For instance, if
you added: alias add /cool http://cool.co:8000/cool, then if a user requested
http://your.server.name:8000/cool then it would work fine, but if he requested
http://localhost:8000/cool or http://your:8000/cool or perhaps the ip, it
wouldn't work at all.<br>
Starting with 1.3.8, you can specify the keyword 'whatever' as host, and thus
match all hosts in the request, like so: alias add http://whatever:8000/cool http://cool.co:8000/cool.<br>
					     </p>
					</li>

					<li> Proxy
					 <p>	You can setup your icecast server as a proxy, which means that all requests for streams on remote hosts 
						    will 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 note that it is very 
										important that the server_name variable is correctly set if you want to run a proxy.
					 </p>
					</li>
				</ol>
			</li>

			<li> <a name="section_static"> Static files (http support) </a>
			     <p>    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.<br>
															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 named 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.
			     </p>
			</li>

			<li> <a name="section_statistics"> Statistics </a>
			     <p>	The icecast server keeps statistics on lots of stuff when running. You can view these either by 
								    using the <a href="#command_stats">stats</a> command or by examining the contents of the file 
												specified by the <a href="#set_stats_log">stats_log</a> 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.<br>
												The <a href="#set_statshtml_log">statshtml_log</a> is also updated regularly and the contents are
												created by parsing templates/statistics.html. You can edit this file and create a statistics file of
												your own.
			     </p>
			</li>

			<li> <a name="section_acl"> Access Control</a>
			     <p>    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.
			     </p>
			     <ol type=I>
				 <li> Libwrap (aka tcp wrappers or tcpd)
				      <p>     
					      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.<br>
											It might even be available for Windows.. not sure about that :)<br>
					      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.<br>
					      More information about libwrap can be found in the manpage for tcpd and hosts_access.<br>
					      You edit the hosts.allow/access file and add the icecast specific stuff, and you can do this while the 
											icecast server is running.<br>
					      Now, what to add?<br>
					      The server (keyword) "icecast" controls <b>all</b> connections, so any host listed here will be affected, 
											no matter what type of connection it is.<br>
					      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.<br>
											Please note that the "icecast" server evaluation takes place long before the type of a connection can
											be established, so if a host is denied access here, it will be denied, even though it might be accepted
											by the "icecast_client" server.<br>
					      Examples:<br>
					      <p>
						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.<br>
						<tt>
							icecast_client: ALL EXCEPT *.se<br>
						</tt>
					      </p>
				      </p>
				</li>

				<li> Internal acl lists
				     <p> 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.<br>
					      You can add acl lists either using the <a href="#command_allow">allow</a> and 
											<a href="#command_deny">deny</a> command on the admin console, or by using the 
											<a href="#set_allow">allow and deny</a> parameters in the icecast.conf file.<br>
					      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.<br>
					      Examples:<br>
					      Like the example above, you want to allow access only to clients from sweden. 
											(this is admin console commands)<br>
					      <tt>
							deny add client *<br>
							allow add client *.se<br>
					      </tt>
				     </p>
				</li>
			     </ol>
		</ol>
  	</li>
	<li> <a name="section_templates"> Template HTML files </a>
	     <p> 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.<br>
										For instance, try http://your.server:port/list.cgi. This will show some statistics and display the connected
										streams on your server, with nice links and everything.<br>
										Now, and this is where templates come in, list.cgi output is created using a template, 
										in this case mountlist.html. In the template you write html code, and icecast will use variable substitution
										on this file for some variables. The variables start and end with an at sign, like @so@.<br>
										Template parsing is used for stats.html generation, list.cgi, the whole 
										<a href="#section_wwwinterface">WWW admin interface</a>, and some other stuff. By editing all files in 
										the icecast/templates/ directory, you can create a whole new look and feel for these pages.<br>
										Someday there will be a manual describing what variables can be used, and how the parsing works, but
										you will get a long way by just browsing through the existing template files and extracting the stuff
										you need.<br>
					</p>
        </li>
	<li> <a name="section_authentication"> Client Authentication Scheme </a>
	     <p> Introduced in version 1.3.1 of icecast, is the client authentication scheme.<br>
		 Designed to be powerful and flexible, yet easy to use.<br>
		 Client authentication uses the Basic Authentication as defined by the HTTP specification.<br>
		 Authentication is defined on a per-mountpoint basis. You specify a number of groups that have
	  access to a certain mountpoint, and then you specify the members in that group, and then you specify
			passwords for the members.<br>
		 Configuration is done in 3 files; users.aut, groups.aut and mounts.aut. Let's follow a bottom-up
		 example. On my server I have 3 streams: reggae, monkeymusic and synth, accessible on the mountpoints
		 http://my.server:port/reggae, http://my.server:port/monkeymusic and http://my.server:port/synth.<br>
		 I have three groups of users; the people on irc channel #icecast, the monkeys in ryd, and the rest of
		 the world. I group these into "icecast", "ryd" and "world".<br>
		 Let's have a look at the user file:<br>
		 <br>
		 <tt>
			eel:somepass<br>
			jack:jackpass<br>
			barath:bpass<br>
			bos:bospass<br>
			lithas:lithepass<br>
			nobody:nopass<br>
		</tt>
		<br>
		One user and pass per line, separated by a colon. The password is in cleartext unless you have compiled the
		server with crypt support.<br>
		Then we look at the group file:<br>
		<br>
		<tt>
			icecast:eel,jack,barath<br>
			ryd:eel,bos,lithas<br>
			world:nobody,eel,jack,barath,bos,lithas<br>
		</tt>
		<br>
		One group per line, with the group name first, followed by a colon and then a comma separated list of 
		users.<br>
		Now to the mountfile:<br>
		<br>
		<tt>
			/monkeymusic:world<br>
			/reggae:icecast<br>
			/synth:ryd,world<br>
		</tt>
		<br>
		One mountpoint per line, with the mountname first, followed by a colon and then a comma separated list of
		groups. There are two special cases in the mountfile. First, you can specify "all" instead of the mountpoint,
		which will make affect all mountpoints. Second, you can specify "rest", which will affect all mountpoints
		not listed in the mountfile. The mountpoints /admin and /oper affect the <a href="#section_wwwinterface">WWW admin interface</a>.<br>
	</p>
	</li>

	<li> <a name="section_wwwinterface">WWW Admin Interface</a>
	     <p>
						The icecast server now has a second admin interface, accessible through the WWW by using any sane
						webbrowser. Access to this interface is restricted in many ways. First you need to set the
						<a href="#set_http_admin">http_admin</a> variable to 1, otherwize no www admins are allowed. Then you
						need to get through the <a href="#section_acl">Access Control</a> system as an admin, and then you
						need a user and password for a user in a group which has access to the /admin and /oper mountpoints.<br>
						Complicated? Not really. If you're using the default values, all you need to do is make sure the 
						Access Control files are in place, and add a group to the /admin and /oper mounts, and a user with password
						to the user.aut file. Then you're inside.<br>
						Someday all of the console commands will be available through the WWW interface, but as of now, only a few
						commands are there. Play with it and see what you think, it's still under heavy development.<br>
						</p>
	</li>

	<li> <a name="section_developer">Developers resources</a>
	     <p> If you want to write your own streaming software, or perhaps a nice streaming mp3 client, go to
						<a href="http://developer.icecast.org/">developer.icecast.org</a>.
						</p>
	</li>
</ol> 
</p>

<hr width="10%">

<p align=right> This document is written by Alexander Haväng [eel@icecast.org].<br>
<!-- hhmts start -->
Last modified: Fri Jun  9 15:07:34 CEST 2000
<!-- hhmts end -->
</p>

</body>
</html>
