icecast2_admin.html 6.81 KB
Newer Older
j's avatar
j committed
1 2 3 4
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
5
<title>Icecast v2.x Documentation</title>
j's avatar
j committed
6 7 8 9
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<body>
<div class="boxtest">
10
<h1>Icecast 2 Admin Interface</h1>
j's avatar
j committed
11
<hr id='titlebar' />
j's avatar
j committed
12 13 14
<br />
<br />
<br />
15
<h2>Overview</h2>
16 17
<p>This section contains information about the admin interface of icecast.  Through this interface the user can manipulate many server features.  From it you can gather statistics, move listeners from mountpoint to mountpoint, disconnect connected sources, disconnect connected listeners, and many other activities.  Each function is enumerated here as well as an example usage of the function.</p>
<p>Each of these functions requires HTTP authentication via the appropriate username and password. For mount-specific functions, you may use either the &lt;admin-username&gt; and &lt;admin-password&gt; specified in the icecast config file, or the username and password specified for that mountpoint (if any). For general functions (not specific to a single mountpoint), you must use the admin username and password. It is also important to note that in all the examples 192.168.1.10 is used as the example host and 8000 is used as the example port for the icecast server.</p>
j's avatar
j committed
18 19 20
<br />
<br />
<br />
21 22
<h2>Admin Functions (mount specific)</h2>
<p>All these admin functions are mount specific in that they only apply to a particular mountpoint (as opposed to applying to the entire server).  Each of these functions requires a mountpoint to be specified as input.
23
</p>
24 25
<h3>Metadata Update</h3>
<h4>description</h4>
j's avatar
j committed
26
<div class="indentedbox">
Ed "oddsock" Zaleski's avatar
doc bug  
Ed "oddsock" Zaleski committed
27
This function provides the ability for either a source client or any external program to update the metadata information for a particular mountpoint. 
28 29 30
</div>
<h4>example</h4>
<pre>
31
http://192.168.1.10:8000/admin/metadata?mount=/mystream&amp;mode=updinfo&amp;song=ACDC+Back+In+Black
32
</pre>
j's avatar
j committed
33 34
<br />
<br />
35 36
<h3>Fallback Update</h3>
<h4>description</h4>
j's avatar
j committed
37
<div class="indentedbox">
vanguardist's avatar
vanguardist committed
38
This function provides the ability for either a source client or any external program to update the "fallback mountpoint" for a particular mountpoint.  Fallback mounts are those that are used in the even of a source client disconnection.  If a source client disconnects for some reason that all currently connected clients are sent immediately to the fallback mountpoint.
39 40 41
</div>
<h4>example</h4>
<pre>
42
http://192.168.1.10:8000/admin/fallbacks?mount=/mystream.ogg&amp;fallback=/myfallback.ogg
43
</pre>
j's avatar
j committed
44 45
<br />
<br />
46 47
<h3>List Clients</h3>
<h4>description</h4>
j's avatar
j committed
48
<div class="indentedbox">
vanguardist's avatar
vanguardist committed
49
This function lists all the clients currently connected to a specific mountpoint.  The results are sent back in XML form.
50 51 52 53 54
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/listclients?mount=/mystream.ogg
</pre>
j's avatar
j committed
55 56
<br />
<br />
57 58
<h3>Move Clients (Listeners)</h3>
<h4>description</h4>
j's avatar
j committed
59
<div class="indentedbox">
vanguardist's avatar
vanguardist committed
60
This function provides the ability to migrate currently connected listeners from one mountpoint to another.  This function requires 2 mountpoints to be passed in: mount (the *from* mountpoint) and destination (the *to* mountpoint).  After processing this function all currently connected listeners on mount will be connected to destination.  Note that the destination mountpoint must exist and have a sounce client already feeding it a stream.
61 62 63
</div>
<h4>example</h4>
<pre>
64
http://192.168.1.10:8000/admin/moveclients?mount=/mystream.ogg&amp;destination=/mynewstream.ogg
65
</pre>
j's avatar
j committed
66 67
<br />
<br />
68 69
<h3>Kill Client (Listener)</h3>
<h4>description</h4>
j's avatar
j committed
70
<div class="indentedbox">
vanguardist's avatar
vanguardist committed
71
This function provides the ability to disconnect a specific listener of a currently connected mountpoint.  Listeners are identified by a unique id that can be retrieved by via the "List Clients" admin function.  This id must be passed in to the request.  After processing this request, the listener will no longer be connected to the mountpoint.
72 73 74
</div>
<h4>example</h4>
<pre>
75
http://192.168.1.10:8000/admin/killclient?mount=/mystream.ogg&amp;id=21
76
</pre>
j's avatar
j committed
77 78
<br />
<br />
79 80
<h3>Kill Source</h3>
<h4>description</h4>
j's avatar
j committed
81
<div class="indentedbox">
82 83 84 85 86 87
This function will provide the ability to disconnect a specific mountpoint from the server.  The mountpoint to be disconnected is specified via the variable "mount".
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/killsource?mount=/mystream.ogg
</pre>
j's avatar
j committed
88 89 90
<br />
<br />
<br />
91 92 93
<h2>Admin Functions (general)</h2>
<h3>Stats</h3>
<h4>description</h4>
j's avatar
j committed
94 95
<div class="indentedbox">
This admin function provides the ability to query the internal statistics kept by the icecast server.  Almost all information about the internal workings of the server such as the mountpoints connected, how many client requests have been served, how many listeners for each mountpoint, etc, are available via this admin function.<br />
vanguardist's avatar
vanguardist committed
96
Note that this admin function can also be invoked via the http://server:port/admin/stats.xml syntax, however this syntax should not be used and will eventually become deprecated.
97 98 99 100 101
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/stats
</pre>
j's avatar
j committed
102 103
<br />
<br />
104 105
<h3>List Mounts</h3>
<h4>description</h4>
j's avatar
j committed
106
<div class="indentedbox">
107 108 109 110 111 112
This admin function provides the ability to view all the currently connected mountpoints.
</div>
<h4>example</h4>
<pre>
http://192.168.1.10:8000/admin/listmounts
</pre>
j's avatar
j committed
113 114 115
<br />
<br />
<br />
116 117 118 119 120 121 122 123
<h2>Web-Based Admin Interface</h2>
<p>As an alternative to manually invoking these URLs, a web-based admin interface was developed.  This interface provides the same functions that were identified and described above but presents them in a little nicer way.  The Web-Based Admin Interface to icecast is shipped with icecast provided in the "admin" directory and comes ready to use.  All the user needs to do is set the path to this directory in the config file via the &lt;adminroot&gt; config variable.</p>
<p>The Web-Based Admin Interface is a series of XSLT files which are used to display all the XML obtained via the URL admin interface.  This can be changed and modified to suit the user's need.  Knowledge of XSLT and transformations from XML to HTML are required in order to make changes to these scripts.</p>
<p>The main URL for the Web-Based Admin Interface is</p>
<pre>
http://192.168.1.10:8000/admin/stats.xsl
</pre>
<p>From this URL all of the other admin functions can be exercised.</p>
124
<p>Modification of existing XSLT transforms in /admin is allowed, but new files cannot be created here. Creation of new XSLT transforms as well as modification of existing transforms is allowed in /web. These work using the document returned by /admin/stats.xml. To see the XML document that is applied to each admin XSLT, just change the .xsl to .xml in your request (i.e. /admin/listclients.xml). You can then code your XSLT transform accordingly.
125
</p>
126 127 128
</div>
</body>
</html>