Shoutcast Server Configuration (Advanced)

1. The 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 one. If you are only working with a single instance then you do not need to add the _# part as any instances of a configuration option will assume it is for _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:

   portbase_1=8080
   portbase_2=8080
   destip_1=stream.server1.com
   destip_2=stream.server2.com

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

   portbase=8080
   destip_1=stream.server1.com
   destip_2=stream.server2.com

The configuration files also allow for comments/notes or options to be disabled by the use of a semi-colon (;) or a left bracket ([) or the hash / pound symbol (#) 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.

1.1. 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.

1.2. 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 Stream Configuration below) 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>]

 

1.3. Debugging

In all cases, the default value is for no debug logging for the options listed below.

yp1debug : Enable debug logging of YP connections

yp2debug : Enable debug logging of YP2 connections

shoutcastsourcedebug : Enable debug logging of SHOUTcast source connections

uvox2sourcedebug : Enable debug logging of SHOUTcast 2 source connections

shoutcast1clientdebug : Enable debug logging of SHOUTcast streaming clients

shoutcast2clientdebug : Enable debug logging of SHOUTcast 2 streaming clients

relayshoutcastdebug : Enable debug logging for SHOUTcast relays

relayuvoxdebug : Enable debug logging for SHOUTcast 2 relays

relaydebug : Enable debug logging of common relay code

streamdatadebug : Enable debug logging of common streaming code

httpstyledebug : Enable debug logging of http style requests

statsdebug : Enable debug logging of statistics

microserverdebug : Enable debug logging of common server activity

threadrunnerdebug : Enable debug logging of the thread manager

rtmpclientdebug : Enable debug logging of rtmp clients

1.4. Flash Security

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

1.5. Introduction and Backup Files

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

introfile : File to play when a client first connects to the server [Default = <no value>] Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

streamintrofile_X : 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>] Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

streambackupfile_X : assigns a specific backup file to a streamID X [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]

1.6. 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.

1.7. 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, 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.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.

faviconfile : Specify the file to be returned as the favicon.ico when the administration pages are being queried by the client's browser [Default = <no value>]

The default behaviour is to use a SHOUTcast themed built-in icon file and support / handling the update of this will entirely depend on the browser.

faviconmimetype : Specify the mime type for actual file to be served in the favicon.ico response [Default = image/x-icon]

Ensure this is correct for the type of image being used so it is valid.

hidestats : Specify if the publically accessible stats?sid=# page can be accessed or if it is only available via the private administration pages [Default = 0]

robotstxtfile : Specify the file to be returned as the robots.txt when queried by search engines, etc to attempt to prevent incorrect access to the server's pages which may cause invalid client connections [Default = <no value>]

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.

User-agent:*

Disallow:/

1.8. 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.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

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.11).

1.9. 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]

2.0. 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]

Setting this to 0 will disable attempts for the relay to reconnect.

relayconnectretries : Specify the number of times relays are attempted to be connected to if it is initially unable to connect [Default = 3]

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.

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.12) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

2.1. Reserved List

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.

 

2.1. 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.11).

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

streamid : Specify the numerical identifier of the stream for control or referencing the stream configuration. This can only be a numeric value from 1 to 2147483647.

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=/live
    or
  streamid_1=1
  streampath_1=/random_mountpoint
  streamid_2=2
  streampath_2=/another_mountpoint

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

If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
http://<serverurl>/<streampath> will work so clients are able to connect.

If this is not specified then http://<serverurl>/stream/<streamid>/ will be
used for client access and in generated playlist entries so that it will
always be possible for clients to connect to the server somehow. See section 6.0 for more information on the
server's stream address support.

streampath is the mountpoint, e.g. streampath_1=/mystation would result in ip:port/mystation

Do NOT specify a streamurl as streampath as this will result in an error.

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

Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

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.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.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 'allowrelay' 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.

2.2. 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]