Difference between revisions of "Icecast Server/Getting Started"

From XiphWiki
Jump to navigation Jump to search
 
(20 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Draft}}
+
This article describes how to get an [[Icecast]] server up and running.
  
This article describes how to get an [[Icecast]] server up and running. On this resulting server you can connect with a Source Client, like [[IceS]], and stream music or video to listener clients. To get started with using Icecast you should first understand how everything works together.
+
On this resulting server you can connect with a Source Client, like [[IceS]], and stream music or video to listener clients.
 +
 
 +
To get started with using Icecast you should first understand how everything works together.
 +
 
 +
[[File:Flowchart icecast.png|500px|thumb|Graphic showing the flow from source clients through Icecast to listeners. (click image to enlarge)]]
  
 
== How it works ==
 
== How it works ==
  
[[File:Flowchart icecast.png|800px|center|Graphic showing the flow from source clients through Icecast to listeners]]
+
The graphic shows how Icecast basically works:
 +
 
 +
* A '''source client''' connects to the '''Icecast server''' on a specified '''mountpoint'''.<br />(a mountpoint can be described as a file on a normal file system)
 +
 
 +
* '''Listeners''' access the '''mountpoints''' ("files") and can listen to the '''bitstreams''' ("file contents").<br />(they can connect to these like they would to normal files on a remote server)
 +
 
 +
* '''Icecast''' offers the bitstream it gets from the source client on a specified mountpoint to all of the mountpoint's listeners in realtime.
 +
 
 +
Note: you cannot use Icecast with static files (eg. [[Ogg]] or mp3 files),<br />
 +
it always needs a source client which sends a bitstream!
 +
 
 +
== Getting Icecast ==
 +
 
 +
You can download Icecast from [http://icecast.org/download/ icecast.org].
 +
 
 +
This guide is written for Icecast version '''2.4.1''', but should work with at least every 2.4.x version.
 +
 
 +
There may be compiled versions on '''Homebrew''' (Mac OS) or '''apt-get''' (Debian, Ubuntu, etc).<br />
 +
Additionally have a look at [[Icecast Server/Installing latest version (official Xiph repositories)|Installing latest version from the official Xiph repositories]], these are the recommended ways to install Icecast.
 +
 
 +
Windows users who download and extract the binary package can skip the '''Compiling''' step and continue with '''Configuration'''.
 +
 
 +
== Compiling ==
 +
 
 +
Only do these steps below, if there is definitely no packages Icecast available for
 +
your system. With a source install you have to manually keep checking for new versions
 +
from time to time and it is not recommended for beginners. Only proceed if you know what
 +
you are doing!
 +
 
 +
Once you have downloaded the source package you want, you have to extract it.
 +
 
 +
After that you have to use your console and change directory (cd) to your extracted files.
 +
 
 +
<pre>
 +
$ cd /path/to/icecast-source
 +
</pre>
 +
 
 +
You then have to run the configuration tool, compile and install it.<br />
 +
(you may have to install additional dependencies first)
 +
 
 +
When done, run the following commands to finish the installation:
 +
 
 +
<pre>
 +
$ ./configure
 +
$ make
 +
$ make install
 +
</pre>
 +
 
 +
== Configuration ==
 +
 
 +
After installing Icecast, you are just one step away from using it! You have to configure it.
 +
 
 +
Icecast is shipped with a default XML configuration file.
 +
 
 +
The file can be found on:
 +
 
 +
* '''Linux''' at: '''/etc/icecast.xml''' or '''/etc/icecast2/icecast.xml'''
 +
* '''MacOS''' at: '''/etc/icecast.xml''' or '''/usr/local/etc/icecast.xml'''
 +
* '''Windows''' at: '''/path-to-extracted-icecast/etc/icecast.xml'''
 +
 
 +
You can edit this file and even save it to a different location.<br />
 +
(you will need its full path to start the server, so remember where you put it)
 +
 
 +
It is '''strongly''' recommended you edit some fields in this XML file,<br />
 +
'''especially''' if you plan to run a '''public''' server.
 +
 
 +
<syntaxhighlight lang="xml">
 +
<location>The server's location</location>
 +
<admin>admin@yourdomain.com</admin>
 +
</syntaxhighlight>
 +
 
 +
You should '''always''' change the passwords from ''hackme'' to something more secure.
 +
 
 +
<syntaxhighlight lang="xml">
 +
<authentication>
 +
    <!-- Sources log in with username 'source' -->
 +
    <source-password>myfancypassword</source-password>
 +
    <!-- Relays log in username 'relay' -->
 +
    <relay-password>youshallnotpass</relay-password>
 +
 
 +
    <!-- Admin logs in with the username given below -->
 +
    <admin-user>admin</admin-user>
 +
    <admin-password>anotherfancypassword</admin-password>
 +
</authentication>
 +
</syntaxhighlight>
 +
 
 +
If you plan to run a public server and/or a server with [[Yellow Pages]] listing,<br />
 +
you should change the hostname to one where your server can be accessed from.
 +
 
 +
<syntaxhighlight lang="xml">
 +
<!-- This is the hostname other people will use to connect to your server.
 +
It affects mainly the URLs generated by Icecast for playlists and YP listings. -->
 +
<hostname>streams.yourdomain.tld</hostname>
 +
</syntaxhighlight>
 +
 
 +
More advanced topics like relays, Yellow Pages listings, etc. are explained in the following in-depth parts of this guide.
 +
 
 +
== Starting the server ==
 +
 
 +
To start your Icecast server, run the following command in your console:
 +
 
 +
<pre>
 +
$ icecast -c /path/to/icecast.xml
 +
</pre>
 +
 
 +
If you did everything correctly Icecast should start and listen for connections on the default port.
 +
 
 +
You can test access to your server by typing [http://127.0.0.1:8000 http://127.0.0.1:8000] into your web browser.
 +
 
 +
If you see a page which says '''Icecast2 Status''' on top,<br />
 +
you have done everything right and finished the basic part of this guide!
 +
 
 +
== What next? ==
  
The graphic above shows how Icecast basically works.
+
If you want in-depth infos, you should look at the following articles.
  
A source client, for example IceS, connects to the server on a specified mountpoint. A mountpoint could be described as a file on a normal local file system.<br />
+
* If you want to start streaming, have a look at [[IceS/Getting Started]]
The listener accesses the mountpoint – the "file" – and can listen to the content – the stream. The server now offers the stream it gets form the source client on that specified mountpoint.
+
* If you want to go deeper into configuring your server, have a look at [[Icecast/Advanced Configuration]]
Now listeners can connect to this mountpoint like they would to a normal file on a remote server.
 
  
Icecast sends the data it receives from the source client to the listeners, to everyone the same bitstream in realtime.<br />
+
[[Category:Icecast]]
It is not possible to use Icecast with static files (like ogg or mp3 files), Icecast always needs an source client which sends the bitstream!
 

Latest revision as of 09:10, 28 June 2017

This article describes how to get an Icecast server up and running.

On this resulting server you can connect with a Source Client, like IceS, and stream music or video to listener clients.

To get started with using Icecast you should first understand how everything works together.

Graphic showing the flow from source clients through Icecast to listeners. (click image to enlarge)

How it works

The graphic shows how Icecast basically works:

  • A source client connects to the Icecast server on a specified mountpoint.
    (a mountpoint can be described as a file on a normal file system)
  • Listeners access the mountpoints ("files") and can listen to the bitstreams ("file contents").
    (they can connect to these like they would to normal files on a remote server)
  • Icecast offers the bitstream it gets from the source client on a specified mountpoint to all of the mountpoint's listeners in realtime.

Note: you cannot use Icecast with static files (eg. Ogg or mp3 files),
it always needs a source client which sends a bitstream!

Getting Icecast

You can download Icecast from icecast.org.

This guide is written for Icecast version 2.4.1, but should work with at least every 2.4.x version.

There may be compiled versions on Homebrew (Mac OS) or apt-get (Debian, Ubuntu, etc).
Additionally have a look at Installing latest version from the official Xiph repositories, these are the recommended ways to install Icecast.

Windows users who download and extract the binary package can skip the Compiling step and continue with Configuration.

Compiling

Only do these steps below, if there is definitely no packages Icecast available for your system. With a source install you have to manually keep checking for new versions from time to time and it is not recommended for beginners. Only proceed if you know what you are doing!

Once you have downloaded the source package you want, you have to extract it.

After that you have to use your console and change directory (cd) to your extracted files.

$ cd /path/to/icecast-source

You then have to run the configuration tool, compile and install it.
(you may have to install additional dependencies first)

When done, run the following commands to finish the installation:

$ ./configure
$ make
$ make install

Configuration

After installing Icecast, you are just one step away from using it! You have to configure it.

Icecast is shipped with a default XML configuration file.

The file can be found on:

  • Linux at: /etc/icecast.xml or /etc/icecast2/icecast.xml
  • MacOS at: /etc/icecast.xml or /usr/local/etc/icecast.xml
  • Windows at: /path-to-extracted-icecast/etc/icecast.xml

You can edit this file and even save it to a different location.
(you will need its full path to start the server, so remember where you put it)

It is strongly recommended you edit some fields in this XML file,
especially if you plan to run a public server.

<location>The server's location</location>
<admin>admin@yourdomain.com</admin>

You should always change the passwords from hackme to something more secure.

<authentication>
    <!-- Sources log in with username 'source' -->
    <source-password>myfancypassword</source-password>
    <!-- Relays log in username 'relay' -->
    <relay-password>youshallnotpass</relay-password>

    <!-- Admin logs in with the username given below -->
    <admin-user>admin</admin-user>
    <admin-password>anotherfancypassword</admin-password>
</authentication>

If you plan to run a public server and/or a server with Yellow Pages listing,
you should change the hostname to one where your server can be accessed from.

<!-- This is the hostname other people will use to connect to your server.
It affects mainly the URLs generated by Icecast for playlists and YP listings. -->
<hostname>streams.yourdomain.tld</hostname>

More advanced topics like relays, Yellow Pages listings, etc. are explained in the following in-depth parts of this guide.

Starting the server

To start your Icecast server, run the following command in your console:

$ icecast -c /path/to/icecast.xml

If you did everything correctly Icecast should start and listen for connections on the default port.

You can test access to your server by typing http://127.0.0.1:8000 into your web browser.

If you see a page which says Icecast2 Status on top,
you have done everything right and finished the basic part of this guide!

What next?

If you want in-depth infos, you should look at the following articles.