Difference between revisions of "SHOUTcast DNAS Server 2"

From Winamp Developer Wiki
Jump to: navigation, search
m (Fixed typo and added future reference to the streamw3clog option)
(Updating YP2 error list to those from the newer YP2 responses)
Line 506: Line 506:
 
Additionally if there is an issue then the server will report an error in its log ouput of 'Connection attempt failed. YP2 error code is XXX (<message>)' where XXX is one of the following error codes and <message> is a message set in the error response to indicate a bit more what the error relates to.
 
Additionally if there is an issue then the server will report an error in its log ouput of 'Connection attempt failed. YP2 error code is XXX (<message>)' where XXX is one of the following error codes and <message> is a message set in the error response to indicate a bit more what the error relates to.
  
470   Invalid authorization hash
+
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
471   Invalid stream type (could be a bad bitrate or mime type)
+
|-
472   Missing or invalid stream url
+
! Status Code
473   Server unreachable by YP
+
! Status Message
474   Relay url does not exist
+
|-
  400    Generic error (covers all other cases usually from not being seen)
+
| 400 || Generic error ''(covers all other cases usually from internal failures)''
 +
|-
 +
| 470 || Invalid authorization hash
 +
|-
 +
| 471 || Invalid stream type (could be a bad bitrate or mime type)
 +
|-
 +
| 472 || Missing or invalid stream url
 +
|-
 +
| 473 || Server unreachable by YP
 +
|-
 +
| 474 || Relay url does not exist
 +
|-
 +
| 475 || Invalid server ID
 +
|-
 +
| 476 || Invalid max clients (value out of range or missing)
 +
|-
 +
| 477 || Terms of Service violator. You are being reported.
 +
|-
 +
| 478 || Incompatible protocol.
 +
|-
 +
| 479 || Streams requiring authorization are not public and cannot list here.
 +
|-
 +
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
 +
|-
 +
| 481 || Cannot verify server since all listener slots are full.  Please wait.
 +
|-
 +
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
 +
|-
 +
| 483 || Invalid listeners (value out of range / missing)
 +
|-
 +
| 484 || Invalid avglistentime (value out of range / missing)
 +
|-
 +
| 485 || Invalid newsessions (value out of range / missing)
 +
|-
 +
| 486 || Invalid connects (value out of range / missing)
 +
|-
 +
| 487 || Request & Response objects are null
 +
|-
 +
| 488 || Request xml is null
 +
|-
 +
| 489 || YP command not specified
 +
|-
 +
| 490 || Generic error, while doing xml parsing
 +
|-
 +
| 491 || Generic error, while reading xml request
 +
|}
 +
 
  
 
'''ypaddr''' : Allows you to specify a different YP server if required    ''[Default = yp.shoutcast.com]''
 
'''ypaddr''' : Allows you to specify a different YP server if required    ''[Default = yp.shoutcast.com]''

Revision as of 16:28, 25 May 2011

Introduction

The purpose of this document is to show you the different configuration options supported by sc_serv along with basic and more advanced example configurations to enable you to get started with using sc_serv and the features it can offer.

The aim of sc_serv is to provide enhanced serving features and also access to the new YP2 infrastructure whilst maintaining as much backward compatibility with previous versions of sc_serv as possible. The new features introduced include:

  1. Serving multiple streams from a single server instance
  2. Relaying multiple streams from a single server instance
  3. Multiplexing all server activity through a single IP port
  4. SHOUTcast 2 wire protocol support for sources, relays and clients
  5. Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
  6. YP2 infrastructure support
  7. Real-time metadata and statistic reporting
  8. Static station id support
  9. In-stream metadata in standardised xml files
  10. UTF-8 and international character encoding
  11. Improved server and stream security


Overview of Features

To take full advantage of the newer features provided as part of the SHOUTcast 2 and YP2 systems then you will need to ensure you are using a compatible version of sc_serv (any version 2 will work) and that you have the required authorisation key to register as a broadcaster on the YP2 directory (see section 3.0).

If you were intending on taking full advantage of the multiplexing and multiple stream support offered as part of sc_serv then you would need to make sure you enable the SHOUTcast 2 options (this is enabled by default with server builds from the end of 2010 if the 'yp2' option in the configuration file is not specified [see section 4.0.14 ). The reason for needing to enable this support is if you try to do it with the original SHOUTcast 1 protocol then it will not work as the original protocol has no means of expressing multiple streams from a single port due to the lack of an identifier provided for them.

If you are planning on connecting multiple sc_trans instances to sc_serv then you must use the SHOUTcast 2 protocol support so that each sc_trans instance can have a unique identifier which allows for multiple streams to then be provided from a single server. It is still possible for an older source to connect to the server with a number of config options available to support this though functionality will be limited compared to what can be done with a fully supporting SHOUTcast 2 source.

Finally clients connecting to your server do not need to directly support SHOUTcast 2 as sc_serv will repackage the stream data and any related metadata into the correct format the client requests (typically based on the user agent detected by the server).


Getting Started

One of the key aspects of the new YP2 directory infrastructure is an authorisation key which is used to validate your server when it tries to connect to the YP2 infrastructure for any of the station(s) you run. Once this key is obtained, it will be valid for all root servers of the station being broadcast.

This can be done by going to http://www.shoutcast.com/my-stations/ where you then obtain a unique authentication key to allow the stream(s) to be listed in the directory. This is a FREE process though may require you to create an account on the SHOUTcast site in order to obtain the needed key.

You can use Yahoo, Google or Facebook accounts for log-in inplace of a new Aol one.

Once you have obtained your authentication key then this needs to be set as the 'streamauthhash' value for your stream (see section 4.0.12 for more details). Additional information about the registration process can be found at this blog posting: http://www.shoutcastblog.com/2010/08/05/broadcaster-registeration-faq/

When using an older SHOUTcast 1 server then you do not need to do this registration and the server will still be able to be listed on the directory but there is not the same level of protection over the stream as is the case with registering it.


Running the Server


The server is able to be run either as a console application or it can be run as service (Windows) or daemon (Linux / Mac OS X / BSD). Detailed below is how to get the server running on the different operating systems supported by it.


Windows


The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7.

Please note that the Windows versions of sc_serv are built with a dependency against the Microsoft Visual C++ 2008 SP1 Redistributable Package. If sc_serv is unable to start due to a dependency issue then you will need to install the correct version of the package so it can run which depends on the version of sc_serv you are attempting to run:

32-bit version: http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version: http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e


Install as a Service


sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service

Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file

If no file / an invalid file is specified then sc_serv will abort loading.

When run as a service there is not a good sense of a current working directory so requires all paths in the configuration and playlist files to be fully qualified otherwise lookups will fail when sc_serv is run.

To run sc_serv with a configuration file in the same folder as the server as the current system user account you would enter into the console:

sc_serv.exe install sc_serv 0 0 sc_serv.conf


Uninstall the Service


sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv


Run as a Non-Service in the Console


sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)

If no file / an invalid file is specified then sc_serv will abort loading.


Linux / Mac OS X / BSD


Remember to enable the required access on the sc_trans file by doing 'chmod a+x sc_trans' after extracting it from the distribution file otherwise the OS is likely to not run it and show the error message './sc_serv: Permission denied'.

Run as a Daemon


./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)

If no file / an invalid file is specified then sc_serv will abort loading.

e.g.

./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.


End a Daemon


kill -SIGTERM <pid> or kill -15 <pid> or kill -s TERM <pid>

<pid> - The PID of the daemon instance (reported when the daemon started or can be found with 'ps ax | grep sc_serv' as long as sc_serv was the file run otherwise you can just use 'ps ax' if the filename isn't known). Additionally the PID of sc_serv is listed in the log file.


Run as a Non-Daemon


./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)

If no file / an invalid file is specified then sc_serv will abort loading.


Configuration File

Here you can find a complete list of all of the configuration options which are provided by sc_serv which ranges from logging to networking configuration and control over the media being used when streaming via the server.

Configuration entries labelled as <MULTI> can be used to set up simultaneous connections to the server or allow for multiple connections from various sources. These are specified by adding _# to the end of the option's name as shown below where # begins with zero not one. If you are only working with a single instance then you do not need to add the _# part as any instances will assume it is _1.

Note: The <MULTI> system is not hierarchical and all values beyond the default must be specified for all connections. So for example, if you wanted to connect to two servers on the same port you must do:

   serverport_1=8080
   serverport_2=8080
   serverip_1=www.server1.com
   serverip_2=www.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

   serverport=8080
   serverip_1=www.server1.com
   serverip_2=www.server2.com

The configuration files also allow for notes or options to be disabled by the use of a comma (;) at the start of a line which can be seen in all of the configuration examples.

Known options in the configuration files are recognised irrespective of the case they are entered in the configuration file so maxuser and MaXuSer will be handled the same way.

Any items found in the configuration file which are not known (as detailed in following sections) or is not processed as a comment will be reported in the following manner:

<date + time> W msg:[CONFIG] Invalid item on line XX

Where <date + time> is the date and time the event happens at and XX is the line in the configuration file where the error has been found to occur at.


Banning


banfile : File to store the list of banned IP addresses [Default = sc_serv.ban]

savebanlistonexit : Re-write the 'banfile' on server exit [Default = 1]

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.


Client Behaviour


maxuser : Specify the maximum number of clients allowed to connect to the server [Default = 32]

This is used in conjunction with 'streammaxuser' (see section 4.0.12) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

listenertime : Specify the maximum time in minutes a client can listen to the stream [Default = 0]

A value of zero means there will be no time limit.

autodumpusers : Enable to allow the server to disconnect clients if the source disconnects [Default = 0]

srcip : Specify the server side binding address for sources to connect on [Default = <no value>]

dstip or destip : Specify the server side binding address for clients [Default = <no value>]

If 'any' or no value is specified then sc_serv listens to all addresses.

If you specify a value for 'dstip / destip' then this will be used by the listen feature on the Administration Pages (see section 5.1) so it can provide a valid stream url in the generated playlist. If 'dstip / destip' is not specified then the server will attempt to auto-generate the IP required for the client to be able to connect. If this fails the generated playlist is likely to return a stream url like http://0.0.0.0:<portbase>/<path>

The IP provided needs to be in a valid format like http://<my-ip> or an address which can be resolved to an IP otherwise the internal lookups done are likely to fail (depends upon the server configuration and OS being used). Also you cannot set srcip and dstip / destip to be the same IP value and if this happens then the server will close. Closing of the server will also happen if the IP cannot be resolved or correctly bound to i.e. server is not there or an invalid value was entered.

titleformat : Specify a string to be used in-place of the default icy-name string being used [Default = <no value>]

urlformat : Specify a string to be used in-place of the default icy-url string being used [Default = <no value>]


Debugging


yp1debug : Enable debug logging of YP connections [Default = 0]

yp2debug : Enable debug logging of YP2 connections [Default = 0]

shoutcastsourcedebug : Enable debug logging of SHOUTcast source connections [Default = 0]

uvox2sourcedebug : Enable debug logging of SHOUTcast 2 source connections [Default = 0]

shoutcast1clientdebug : Enable debug logging of SHOUTcast streaming clients [Default = 0]

shoutcast2clientdebug : Enable debug logging of SHOUTcast 2 streaming clients [Default = 0]

relayshoutcastdebug : Enable debug logging for SHOUTcast relay [Default = 0]

relayuvoxdebug : Enable debug logging for SHOUTcast 2 relay [Default = 0]

relaydebug : Enable debug logging of common relay code [Default = 0]

streamdatadebug : Enable debug logging of common streaming code [Default = 0]

httpstyledebug : Enable debug logging of http style requests [Default = 0]

statsdebug : Enable debug logging of statistics [Default = 0]

microserverdebug : Enable debug logging of common server activity [Default = 0]

threadrunnerdebug : Enable debug logging of the thread manager [Default = 0]

rtmpclientdebug : Enable debug logging of rtmp clients [Default = 0]


Flash Security


flashpolicyfile : Name of file containing flash crossdomain policies on the server [Default = crossdomain.xml]


Introduction and Backup Files


introfile : File to play when a client first connects to the server [Default = <no value>]

backupfile : File to play if the source disconnects from the server [Default = <no value>]

specialfiletmpdir : place to store intro and backup files uploaded by sc_trans [Default = /tmp/ (*nix only)]

maxspecialfilesize : Change the maximum size in bytes of the backup and intro files [Default = 30000000]


Logging


log : Enable logging of the servers output [Default = 1]

screenlog : Enable logging of servers output to the console [Default = 1]

If log=0 then this option is ignored due to no logging happening.

logfile : Specify a different logfile to save the logs into [Default = %temp%\sc_serv.log or /tmp/sc_serv.log]

logclients : Enable logging of details about client connections and disconnections made [Default = 1]

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.


Miscellaneous


configrewrite : Re-write the 'config file' on server exit [Default = 0]

songhistory : Specify the maximum song history to preserve [Default = 10]

cpucount : Specify the number of cpu's present instead of the calculated number if non-zero [Default = 0]

unique : Specify a substitution string for the '$' character to be used when processing filenames which if specified will set any occurences of '$' to the value set. This will be used in the processing of the following filenames: logfile, introfile, streamintrofile, backupfile, streambackupfile, banfile, streambanfile, ripfile, streamripfile, include, contentdir, w3clog, streamw3clog

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

include : Specify an additional include file containing settings to be processed from the current point in the main configuration file [Default = <no value>]

You can do multiple calls of this allowing for a basic configuration file with then 'specific' stream configurations set in individual conf files though you need to ensure not to include a reference to the same file in itself.

You can also specify a path with a wildcard for sc_serv to use to find multiple configuration files to include e.g. 'include=stream/*.conf'. This can then be used along with the multiple stream configurations (see section 4.0.12) and the admin command 'admin.cgi?mode=reload' (see section 5.1) to add / remove / update stream configurations without having to close the server to apply them.

admincssfile : Specify the css styling to be used on the index.html and admin pages [Default = v2]

This can accept the following parameters:

admincssfile=v1 - Uses the v1 DNAS style
admincssfile=v2 - Uses the newer SHOUTcast 2 style
admincssfile=path_to_local_css_file e.g. my_index.css</nowiki>
If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.


Networking


namelookups : Enable to allow reverse DNS look-ups on incoming IP addresses [Default = 0]

portbase : Specify the port which clients and sources need to use to connect to the server [Default = 8000]

SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

autodumpsourcetime : Specify how long before an idle source is dumped from the server (in seconds) [Default: 30]

A value of zero means there is no timeout of an idle source.

maxheaderlinesize : Specify the maximum size of an HTTP header line [Default = 2048]

maxheaderlinecount : Specify the maximum header lines in an HTTP style exchange [Default = 100]

adminpassword : Specify the administrator password for accessing the remote server features [Default = <no value>]

password : Specify the password for broadcasters when connecting to the server [Default = <no value>]

This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.0.11).


Network Buffers


buffertype : Specify whether the buffer size is fixed [0] or adaptive [1] [Default = 0]

adaptivebuffersize : Specify the buffer size in seconds if buffer is set to adaptive [Default = 1]

fixedbuffersize : Specify the buffer size in bytes if the buffer is set to fixed [Default = 1048576]

bufferhardlimit : Specify the maximum buffer size in bytes which it can never go above [Default = 16777216]


Relaying


allowrelay : Enable to allow a relay to connect to the server [Default = 1]

allowpublicrelay : Enable to allow relays to list themselves in the YP directory [Default = 1]

relayreconnecttime : Specify how many seconds to wait to reconnect on a relay failure [Default = 30]

maxhttpredirects : Specify the maximum number of times we can redirect when relaying [Default = 5]

<Legacy Options>

relayport : Port of the source to use for the relay [Default: 80]

relayserver : Url of the source to relay [Default = <no value>]

Using the stream configuration options (see section 4.0.12) is the
prefered method of setting up a relay and these options should only be used if absolutely required.


Reserved IP (RIP)


ripfile : File to store the list of reserved IP addresses [Default = sc_serv.rip]

saveriplistonexist : Re-write the 'ripfile' on server exit [Default = 1]

riponly : Only allow connections to be made from reserved IP addresses [Default = 0]

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.


Stream Configuration


Important Note: If you do not specify an identifier (_#) on the end of the above options then it will be treated like _1 (effectively acting like SHOUTcast 1). Additionally, _0 is not a supported identifier and will be mapped to _1.

requirestreamconfigs : Only allow sources to connect if a stream configuration has been set in our configuration file [Default = 0]

With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see sc_trans.txt - section 3.0.11).

<MULTI> (one set for each stream configuration):

streamid : Specify the identifier of the stream as used to control or reference the stream e.g. from the admin pages. streamid : Specify the identifier of the stream for control or referencing the stream.

If this is not specified then no valid stream configurations will be known which is often
going to cause issues if running the the yp2 mode enabled (as is done by default).

If you use multiple stream configurations then you will need to ensure the _X part is
specified and correct for each stream configuration group
e.g.
  streamid=1
  streampath=/random
    or
  streamid_1=1
  streampath_1=/random_stream_path

  streamid_2=2
  streampath_2=/another_stream_path

streamauthhash : The authorisation key needed for YP2 directory registration.

This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see section 3.0).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

streampath : Specify the path clients need to use to access the stream

This generally needs a / on the start of the string to work. As well this defines the
stream's url and without it clients will not be able to correctly connect / will show an error.

Additionally this relates to the 'endpointname' config item when using sc_trans (see sc_trans.txt - section 3.0.11).

streamrelayurl : Specify the full url of source to relay (if this is a relay).

Make sure if you use this that the full url entered is visible publically when working with
a public stream configuration else the YP connection is likely to fail with a 474 error code message.

streammaxuser : Specify the maximum number of clients allowed to connect to the stream [Default = 0] If set to zero, not specified or higher than 'maxuser' then the value set for 'maxuser' (see section 4.0.2) will be used for all knwon streams.

Changing this to a value between zero and 'maxuser' will enforce the user connection limit for the specified value in the stream configuration e.g.

streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration

streammaxuser_1 = 64
maxuser = 32

This allows a total of 32 connections to the server but with a per stream limit above the maximum means the maximum number of connections to the first stream group will be 32. However this also depends upon any other stream configurations and their limits as to whether 32 clients will be able to connect to this stream configuration.

Finally unless a valid stream configuration is specified then this value will only be applied to the first stream configuration found i.e. there is a need to specify a streamid_XXX for streammaxuser_XXX (where XXX is the stream identifier of the stream configuration group.

streamadminpassword : Specify the administrator password for accessing the remote server features for the specified stream configuration group. If this is not specified then 'adminpassword' will be used.

streampassword : Specify the password for broadcasters when connecting to the server for the specified stream configuration group. If this is not specified then 'password' will be used.

This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.0.11).

streampublicserver : This allows you to override the public flag received from the source when a connection is being made to the YP directory. If this is not specified or is set to empty then 'publicserver' will be used.

streamallowrelay : Enable to allow a relay to connect to the server. If this is not specified then 'allowpublicrelay' will be used.

streamallowpublicrelay : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

streamriponly : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

streamautodumpsourcetime : Specify how long before an idle source will be dumped from the server (in seconds). A value of zero means there is no timeout of an idle source. If not specified then 'autodumpsourcetime' will be used.

streamautodumpusers : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

streamlistenertime : Specify the maximum time in minutes a client is allowed to listen to the stream. A value of zero means there will be no time limit. If not specified then 'listenertime' will be used.

streamintrofile : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

streambackupfile : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

streambanfile : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

streamripfile : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

streamw3clog : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.


Web Connection (W3C) Logging


w3cenable : Enable logging of web connections to describe the duration a client has listened to a specific title [Default = 1]

w3clog : File to store the web connections logs into [Default = sc_w3c.log]

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

webclientdebug : Enable logging of web client connections [Default = 0]


YP Server Behaviour


uvoxcipherkey : Specify the key used to obfuscate the initial handshaking with the source [Default = foobar]

This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see sc_trans.txt - section 3.0.3).

Only change this if you really need to do so as not all SHOUTcast 2 clients will allow you to edit this value from the default value. If using the Source DSP plug-in then see dsp_sc.txt - section 5.0 for details on how to change the plug-in to use a differnet value.

metainterval : Specify the metadata transmission interval in bytes [Default = 8192]

YP1 only

yp2 : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory [Default = 1]

If this is enabled and not all of the required values are set then the server will throw an error and will abort from its start-up attempt. It should be indicated what needs to be set to allow the server to start with this set.

Additionally if there is an issue then the server will report an error in its log ouput of 'Connection attempt failed. YP2 error code is XXX (<message>)' where XXX is one of the following error codes and <message> is a message set in the error response to indicate a bit more what the error relates to.

Status Code Status Message
400 Generic error (covers all other cases usually from internal failures)
470 Invalid authorization hash
471 Invalid stream type (could be a bad bitrate or mime type)
472 Missing or invalid stream url
473 Server unreachable by YP
474 Relay url does not exist
475 Invalid server ID
476 Invalid max clients (value out of range or missing)
477 Terms of Service violator. You are being reported.
478 Incompatible protocol.
479 Streams requiring authorization are not public and cannot list here.
480 Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
481 Cannot verify server since all listener slots are full. Please wait.
482 This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
483 Invalid listeners (value out of range / missing)
484 Invalid avglistentime (value out of range / missing)
485 Invalid newsessions (value out of range / missing)
486 Invalid connects (value out of range / missing)
487 Request & Response objects are null
488 Request xml is null
489 YP command not specified
490 Generic error, while doing xml parsing
491 Generic error, while reading xml request


ypaddr : Allows you to specify a different YP server if required [Default = yp.shoutcast.com]

ypport : Allows you to specify the port of the YP server if required [Default = 80]

ypPath : Allows you to specify the path to YP2 services on the server [Default = /yp2]

ypTimeout : Specify the timeout interval in seconds for requests made to the YP server [Default = 60]

ypmaxretries : Specify the maximum number of times a YP request will be attempted [Default = 10]

This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

ypreportinterval : Specify the maximum time in which the YP must have contacted our server in seconds [Default = 300]

ypminreportinterval : Specify the minimum time in which the YP can contact our server in seconds [Default = 10]

publicserver : This allows you to override the public flag from the connected source when a connection is being made to the YP directory [Default = default] This can be one of the following values:

default - use the flag provided by the source
always - force the source to be public
never - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see sc_trans.txt - section 3.0.8).


Administration

With sc_serv there are administration pages available for accessing and controlling the server remotely which allows you to monitor and control clients connected to the stream (or not if banning them). These pages can now be accessed through a summary page at /index.html which will show a link to any active stream(s) or you explicitly access them via the /index.html?sid=# path where # is the ID of the stream (see section 4.0.12 for more about using 'streamid') e.g.

<streamurl>/index.html?sid=1

If no sid or an invalid sid is passed then you will be taken to the summary /index.html and this will be applied even if you were on a page with a known ID and then enter an invalid sid or remove it purposefully.


Administration Pages


As part of the administrative features provided there are the following pages where # is the streamid you want to use). This is not a complete list but should cover all of the pages which allow for a direct http url to be entered to get an administation action to work. The ban and reserve IP actions require input fields and do not map to direct sends.


Public Pages


index.html - Shows a summary page with links to get to any active stream(s)

currentsong?sid=# - Returns the current song title or a null response

nextsong?sid=# - Returns the next song title (if known) or a null response

currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

nextsongs?sid=# - Returns in an xml format the next song title(s) (if known) to be played when using a compatible v2 stream source.

The titles are in the form of <title seq="xx">title</title> where
'xx' is the number of the song in the list beginning at "1".

index.html?sid=# - Shows current status of the specified stream

played.html?sid=# - Song history of specified playing history

or

played?sid=#

listen.pls?sid=# - Provides a pls for clients to use to connect to the stream.

or

listen?sid=#

listen.m3u?sid=# - Provides a m3u for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.0.2) or leave empty and allow the server to attempt to auto-generate
the IP required for the client to be able to connect. If this fails the generated
playlist is likely to return a stream url like http://0.0.0.0:<portbase>/<path>

home.html?sid=# - Opens in a new window or tab (depending on the client browser) the 'streamurl' as specified by the stream source. If this is not set then the client will be redirected to the shoutcast.com main page.

or

home?sid=#


Private Pages


By passing &pass=password where password is the 'adminpassword' (see section 4.0.8) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with YWRtaW46
e.g.
    &pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

admin.cgi - Shows the an overal summary admin page for the streams provided by the server including direct links to certain information pages (see notes about the 'admin.cgi?sid=#&mode=viewxml' command for more info)

or

admin.cgi?sid=0

admin.cgi?sid=# - Shows the base admin page for the stream and information

admin.cgi?sid=#&mode=updinfo&song=title_to_show

If 'title_to_show' is not empty then what is passed will be set as the current title of the stream
playing until the next use of this action or the next title update is received from the source.

admin.cgi?sid=#&mode=viewlog - View logfile

admin.cgi?sid=#&mode=viewlog&viewlog=tail - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See section 4.0.6 for more information on the log file.

admin.cgi?sid=#&mode=viewban - Ban view which matches the ban file and allows you to ban a single IP or an IP range from it (see section 4.0.1 for more info on the file)

admin.cgi?sid=#&mode=viewrip - Reserved IP list that matches the rip file (see section 4.0.11 for more info on the file)

admin.cgi?sid=#&mode=viewxml - Returns an xml output of the current stream information

or

admin.cgi?sid=#&mode=viewxml&page=#

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

    1 - Server Summary
    2 - Webdata Stats          (currently disabled in the builds from early 2011)
    3 - Listener Stats
    4 - Song History
    5 - Stream Metadata        (if supported by the source otherwise can just be title)
    6 - Stream Configurations  (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

admin.cgi?mode=resetxml&sid=# - Will flush the held stream information to refresh it

admin.cgi?sid=#&mode=kicksrc - Will allow you to kick the currently connected source for the specified stream.

admin.cgi?sid=#&mode=unripdst&ripdst=<IP> - Where <IP> is the IP to reserve (see section 4.0.11 for more information).

admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0 - Where <IP> is the first 3 parts of a subnet IP to unban.

admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255 - Where <IP> is that of a single IP to unban.

admin.cgi?mode=reload

or

admin.cgi?mode=reload&force=1 - This reloads the stream configuration details in the main configuration file the server used when started and is only available on the admin summary page and so can only be run by the master administrator password.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream e.g. not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

    password or streampassword (*)            streamadminpassword (#)
    requirestreamconfigs                      streamid
    streamauthhash                            streampath
    streamrelayurl                            streammaxuser
    streampublicserver                        streamallowrelay
    streamallowpublicrelay                    streamriponly
    streamautodumpsourcetime                  streamautodumpusers
    streamlistenertime                        streamintrofile
    streambackupfile                          streambanfile
    streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server


Stream Addresses

Clients connecting to the streams provided by sc_serv are able to so in a number of ways depending upon how the streams have been configured and also depending upon the number of streams you have available.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/

or

<serverurl>/<streampath>
<serverurl> is typically formed as http://dstip:portbase (see sections 4.0.2 and 4.0.8)
<streamid> is the 'streampath' set from the stream configuration (see section 4.0.12)
<streampath> is the 'streampath' set from the stream configuration (see section 4.0.12)

If the client attempting to connect to the server instance does not specify <streampath> or <streamid> in the stream url it attempts to access or if only one stream is provided then the server will usually default to the first stream it knows about and will allow the client to make a valid connection.

This handling of the stream addresses provided is something to keep in mind especially if you are providing multiple streams as this will allow you to provide different addresses for certain clients to be able to use a specific stream e.g. if you wanted to have mobile clients connect to a lower bandwidth stream then you could direct them to '<serverurl>/mobile'

The server options available for controlling how the stream's path is specified can be seen in section 4.0.12 which also details the equivalent values needing to be set in the sc_trans configuration if you use sc_trans to provide a source to sc_serv.


Locale Error (Linux / Mac OS X / BSD)

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what():  locale::facet::_S_create_c_locale name not valid
Abort trap

If this happens then you need to set the 'POSIX' locale in your terminal's environment values. If this does not happen then everything is fine or you are using a newer version of sc_serv from the end of 2010 which should no longer exhibit this issue.

Linux:

export LC_ALL=POSIX

BSD:

setenv LC_ALL POSIX

Mac OS X:

export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"


Virtual Memory Footprint (Linux / Mac OS X / BSD)

Due to how sc_trans works it will create a large number of threads which may become an issue due to the default virtual memory stack allocation per thread potentially being large (typically 10MB per thread). For most people this should not be an issue as the memory is not really allocated unless it is used. If however if you have a resource constrained system or if you plan on running many copies of sc_trans then you could potentially run out of virtual memory.

The default thread allocation can be reduced by issuing a "ulimit" command before running sc_trans and in the example reduces it to 512KB per-thread e.g. ulimit -s 512


Example Configurations

Include as part of the sc_serv installation are a number of example configurations to get things started with using some of the features of the server. The provided examples are:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

All of the configuration examples are documented and will relate back to details in this file appropriately. You will need to change some details in these example files or to obtain any applicable authorisation keys for the setup you are making (see section 3.0). In all cases the examples are designed to work from the same install folder as sc_serv.

Remember these examples are a way to get you up and running faster though you are still likely to have to adjust things depending upon the systems you are using and how you want to manage your sources and server connections which are covered in previous sections.

Additionally if you are not happy with editing the files or find it still too confusing then you can use the configuration builder which (if installed) can be found in the 'config_builder'. Open 'config_builder.html' in your browser and then use this graphical tool to setup a configuration file for the server (and additionally the transcoder).


sc_serv_basic


This is the base configuration from which the other configuration examples are based and this will get a sc_serv instance running as a local setup with no connection made to the YP directory.


sc_serv_public


This configuration file changes the required options in the sc_serv_basic configuration to get a sc_serv instance running as a public setup with a connection made to the YP for listing the stream in the directory. This shows the use of the 'include' option (see section 4.0.7) and how specifying a configuration option twice uses the last value found.


sc_serv_relay


This configuration file changes the required options in the sc_serv_public configuration to get a sc_serv instance running as a public setup with a source coming in from a relay server providing a SHOUTcast 2 stream.


sc_serv_debug


This configuration file can be included in any other configuration files to allow you to get debug logging output when trying to investigate any issues you may be experiencing.


sc_serv_simple


Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

This configuration file is designed to be used just as is and is the simplest form of the configuration file you can have which will allow you to get a running server to appear on the YP. This works on using the default settings of the server though does change some of the file paths inorder to fit in with the existing setup as used in the other examples.

All you need to do when using this configuration file is to enter your authorisation key in the 'streamauthhash' line e.g. if your authorisation key is 123456789 then you change streamauthhash=<enter_your_auth_key_here> to streamauthhash=123456789 and save the file.