Using centovacast.conf

Using centovacast.conf

The main Centova Cast configuration file, /usr/local/centovacast/etc/centovacast.conf, contains many options for modifying the behavior and appearance of Centova Cast's web interface.

A non-exhaustive list of the options available in centovacast.conf is provided below.

Database connection options

DB_NAME

Specifies your MySQL database name.

DB_USER

Specifies your MySQL database username.

DB_PASS

Specifies your MySQL database password.

DB_HOST

Specifies your MySQL database hostname. Typically this is localhost unless your MySQL server is running on a separate machine.

Default: localhost

Locale configuration

LOCALE

Set the default locale to use for Centova Cast's internationalization features. To see if your locale is supported, look in the /usr/local/centovacast/system/locale/ directory.

Note that each user can also change his own locale in his account settings, thereby overriding this setting for his account only.

Default: en_US

Feature Configuration

FETCH_NEWS

Controls whether Centova Cast will periodically retrieve news from centova.com to display in the admin area.

Default: true

RECENT_TRACK_LIMIT

Sets an upper limit on the number of tracks that may be returned by the Recent Tracks lists in Centova Cast. Note that this may be further limited by the streaming server itself, and by the user in the Recent Tracks widget configuration.

Default: 20

Date and Time

NOTE: The date and time format is updated automatically when you change your locale, and typically does not need to be set here. Uncomment and set these options only if you do not wish to use the default date/time formats for your locale. Note that this will override the formatting for ALL locales on your system, even if your users have chosen a different locale than the server default.

See http://php.net/manual/en/function.date.php for a list of formatting codes that can be used in these settings.

OVERRIDE_TIMEFORMAT

Time format.

Default: h:i A

OVERRIDE_DATEFORMAT

Full date format.

Default: M d, Y

OVERRIDE_NODAYFORMAT

Date format, no day.

Default: M, Y

OVERRIDE_NOYEARFORMAT

Date format, no year.

Default: M, d

Track Information Formatting

NOW_PLAYING_FORMAT

Controls the formatting of the "now playing" text displayed in the Centova Cast client area and stream info widgets.

%artist% = artist name
%title% = track title
%album% = album name
%playlist% = playlist name (if on autoDJ)

Set this to an empty value (do NOT comment out) to use the text from the streaming server verbatim.

Default: %artist% - %title%

POSTPROCESS_TRACK_INFO

Specifies whether extraneous data is removed from the artist, album, and song title before display in Centova Cast's client area, stream info widgets, recent tracks widgets, etc. Extraneous data includes text in parentheses at the end of the artist/album/title, track numbers embedded in the title, filename extensions, and other often-undesirable cruft.

Note that this is a display setting only; it does not affect how media is imported. See PREPROCESS_TRACK_INFO below to change import behavior.

Default: true

PREPROCESS_TRACK_INFO

Specifies whether extraneous data is removed from the artist and album during the import procedure's artist and album identification process. This ensures that minor differences in artist/album name are correctly handled; for example, tracks whose artists are set to "DJ Foo featuring DJ Bar" or "DJ Foo (Live)" will both be filed under the artist entry for "DJ Foo".

To use artist and album names verbatim, without any such processing, set this to false.

Default: true

Event Scripts

EVENT_SCRIPTS

If enabled, the event scripts under /usr/local/centovacast/var/events will be called in response to various events within Centova Cast.

Default: false

EVENT_SCRIPT_TIMEOUT

Specifies the maximum amount of time (in seconds) for which an event script may run before being terminated by Centova Cast. This should be set high enough to allow your event scripts to complete normally, but low enough to not cause unnecessarily long delays in the web interface. Note that in most cases, event scripts are called while a user waits for the web interface to perform a task, so this directly affects the user's experience.

Default: 30

Log Processing

MAX_ARCHIVED_LOGS

Sets the maximum number of archived log files to keep (i.e., error.log.1, error.log.2, etc.) after the logs are rotated.

Default: 4

LOCALIPADDRESS

Specifies one or more IP addresses, separated by commas, to completely exclude from log file processing.

LOGPROCESS_MIN_DURATION

Specifies the minimum duration (in seconds) for a listener session to be recorded in the statistics; sessions shorter than this value will not be recorded. Set to 0 to record ALL sessions regardless of duration.

Default: 0

LOGPROCESS_MAX_DURATION

Specifies the maximum duration (in seconds) for a listener session to be recorded in the statistics; sessions longer than this value will not be recorded. Set to 0 to record ALL sessions regardless of duration.

Default: 0

Privileges and Policy Enforcement

CLIENT_ENCODER_SETTINGS

If enabled, clients will be permitted to edit their own encoder settings (including sample rate, channels, and so-on).

Default: false

CLIENT_BITRATE_MODIFY

If enabled, clients will be permitted to edit their own bit rate limit.

Default: false

BITRATE_LIMIT_ENFORCE

If enabled, Centova Cast will enforce bit rate limits normally per the settings configured by the admin on the Centova Cast settings page.

If disabled, Centova Cast will only trigger the bitrate-exceeded event script when a client exceeds his bit rate limit, allowing the admin to perform custom handling of the violation. The stream will not be shut down, the account will not be suspended, and the Bit Rate Limit Exceeded email will not be sent.

Default: true

BITRATE_LIMIT_IGNORE

If enabled, Centova Cast will completely skip the bit rate check. Clients will be permitted to broadcast with a live source at any bit rate.

Default: false

ICECAST_TRUST_AUDIOINFO

IceCast does not provide a mechanism to determine the actual bit rate of the streams received from live sources. Live sources may voluntarily report a bit rate, and that information is usually accurate, but theoretically a false bit rate could be reported and this could allow a user to exceed his stream's bit rate limit.

Disabling this option will force Centova Cast to ignore the bit rate voluntarily reported by the live source for the purposes of bit rate limit checking.

Default: true

VERIFY_UNCONFIRMED_BITRATES

If an IceCast live source does not voluntarily report its bit rate, or if ICECAST_TRUST_AUDIOINFO is set to false, enabling this option causes Centova Cast to connect to the audio stream and manually determine the actual bit rate at which the source is broadcasting.

This ensures accurate bit rate enforcement, however it will dramatically slow down the bit rate checker cron job, and will pollute the streaming server's logs with periodic test connections. These connections will not, however, affect the statistics displayed in Centova Cast.

Note that SHOUTcast DNAS always provides an accurate bit rate measurement, so this option does not affect DNAS or DNAS2 streams.

Default: true

VERIFY_ALL_BITRATES

Enabling this option should never be necessary, however it forces Centova Cast to manually verify the bit rates of EVERY stream in the manner described above for VERIFY_UNCONFIRMED_BITRATES.

Default: false

REQUIRE_SSL

If enabled, Centova Cast will automatically redirect non-secure (http://) requests to the secure (https://) web interface, thereby requiring the use of SSL.

Default: false

Directories and Path Traversal

MEDIA_PARTITION

By default, the disk usage graph at the top of the accounts page in the admin area is based on the free space on whichever partition holds your Centova Cast "vhosts" directory.

If you need to check the space on another partition instead (e.g. if you use symlinks to reference media on another partition), specify the path to the alternate partition here.

QUOTA_SPOOL_ONLY

If enabled, the user's disk quota will only apply to files uploaded to the /usr/local/centovacast/var/vhosts/USERNAME/var/spool/ directory and its subdirectories; any configuration files, log files, etc. will be excluded from the quota. Note that cc-ftpd does not honor this setting (due to technical limitations) and will always apply the quota ONLY to the spool directory, regardless of this setting.

Default: true

Streaming Server Hostnames

SELFREF_HOSTNAME

Set this to TRUE if self-referencing links (such as the link to the ShoutCast administration page, and the links to tune into the server) should use the hostname configured for the stream or server instead of its IP address.

Note that enabling this WILL BREAK YOUR STREAMS if you have not correctly configured DNS for the hostnames you've specified. DO NOT ENABLE THIS UNLESS YOU FULLY UNDERSTAND THE CONSEQUENCES OF DOING SO.

Default: false

SELFREF_OVERRIDE

Set this to an IP address or hostname to override the hostname portion of all self-referencing links. Note that before enabling this, you should ensure that:

  1. All of your streams are configured to listen on the same IP address, and
  2. The IP address or hostname below corresponds to the IP address on which your streams are configured to listen.

This may be useful for NAT configurations or to force a specific hostname for other purposes. Be aware, however, that enabling this completely eliminates the ability to control multiple hosting servers with a single Centova Cast web interface.

In a nutshell, you should probably never enable this.

Example: SELFREF_OVERRIDE=foo.example.com

HOSTNAME_FROM_HOST

Set this to true if new accounts whose hostnames are set to "auto" (such as those provisioned through billing modules) should receive the same hostname the host server upon which they are provisioned. Set to false to use the stream's IP address as its hostname.

Default: true

Media Library

ALBUM_COVER_WIDTH / ALBUM_COVER_HEIGHT

Specifies the dimensions to which album cover images will be resized. Note that further width/height restrictions may be imposed on the display of these images by cascading stylesheets.

Default: 60

ALLOW_IMPORT_M3U

If enabled, users will be permitted to import M3U playlist files into Centova Cast playlists. This option is disabled by default as it was added as a courtesy for a small group of advanced users who requested it, and it is NOT SUPPORTED IN ANY CAPACITY by Centova Technologies due to the complexities of getting the relative paths correct. Be sure to read this article before enabling.

Default: false

DISABLE_FOLDER_VIEW

If set to false, the user will be able to browse his media library by folder. Note that this is a different feature than the File Manager, and will likely be removed in a future release as it largely duplicates the File Manager's functionality.

Default: false

UPLOAD_EXTENSIONS

Specifies the file types (file extensions) that users will be permitted to upload via the web-based File Manager.

This list is intentionally restrictive and in most cases shouldn't be modified. Don't do something silly like allowing users to upload scripts.

Also note that this option is commented out by default to allow Centova Cast to automatically generate its own accepted-file-types list, which may include additional file formats in future as we add support for new audio/video streaming formats. If you uncomment this and set your own file types, you will need to manually add new file formats to it in future. Default: mp3,ogg,aac,aacp,wma,wmv,jpg,jpeg,gif,png,txt,m3u,xspf,pls

UPLOAD_SIZE_LIMIT

Specifies the maximum file size that will be accepted by the web-based File Manager's file uploader. This is a per-file limit. Be conservative; web-based uploads aren't very robust (on the server nor client side) and tend to have problems with large files. Encourage users to use FTP for very large files (greater than 100MB or so).

Default: 104857600

IMPORT_ALL_TAGS

If enabled, Centova Cast will import all meta tags (e.g., ID3 tags and similar) into its database for use within Centova Cast. Notably, these tags will be available in the downloadable CSV reports. Enabling this option will reduce the performance of media library updates, and may substantially increase the size of your database.

Default: false

IMPORT_BIN_TAGS=false

When IMPORT_ALL_TAGS is enabled, Centova Cast normally imports only textual tags and skips binary tags (i.e., embedded pictures and such). Enabling this option will import binary tags as well. Note that these tags are NOT used at all in Centova Cast and will substantially increase the size of your database; this option is only useful if you are using third-party scripts which access the Centova Cast database.

Default: false

FILEMODE_SPOOL

Specifies the default file mode (permissions, in octal notation) for files uploaded via the web interface to the user's spool/ directory and its subdirectories, including the media/ directory. (Note that this does not apply to files uploaded via FTP.)

Default: 0660

FILEMODE_ONDEMAND

Specifies the default file mode (permissions, in octal notation) for files uploaded via the web interface to the user's spool/ondemand/ directory. (Note that this does not apply to files uploaded via FTP.)

Default: 0664

AutoDJ

AUTODJ_FAILSAFE

If a stream's autoDJ is set to "Permitted and enabled", and Centova Cast detects that an live DJ has used the "Deactivate source" option to temporarily turn off the autoDJ, but no source is connected, this option will cause Centova Cast to automatically restart the autoDJ. This can be useful in case a live DJ disconnects and forgets to reactivate the autoDJ.

Note that this will have NO EFFECT if the autoDJ is set to "Disabled", and is only checked when the cron job runs so the reactivation may be delayed.

Default: true

RANDOM_UNIQUE_PERIOD

Limits identical song playbacks within a given period (in minutes); refer to this article for details.

Default: 360

ICES_METADATA_FORMAT

Enter the metadata format for use with ices-cc realtime track selection. This will display in the listener's media player, the recent tracks list, and so-on.

Example: ICES_METADATA_FORMAT='%artist% - %album% (%releaseyear%) - %title% (%bitrate%kbps, %length% seconds)'

Default: %artist% - %title%

Optimization

OPTIMIZE_HTML

If enabled, Centova Cast will optimize its HTML output, removing all unnecessary whitespace, comments, and other content unnecessary for page rendering. Leaving this enabled is strongly recommended for production use as it reduces page load time and bandwidth usage, however if you are modifying Centova Cast's templates and need to use your browser's View Source feature you may want to temporarily disable this for testing.

Default: true

CORS

SESSION_API_CORS_ORIGIN

The session API is accessed via AJAX requests which may be restricted by browsers' CSRF- prevention mechanisms. If you need to make requests to the session API from pages on a domain name other than that on which Centova Cast is hosted, specify an appropriate value for the Access-Control-Allow-Origin header using this setting.

If you're not a developer and you don't know whether you're using the Session API, you're almost certainly not, and you shouldn't enable this.

Default: (disabled)

Process launching & monitoring

SKIP_PROCESS_CHECK

If enabled, Centova Cast will stop monitoring all server/autoDJ processes. This means if a server/autoDJ crashes/etc. it will remain offline until manually restarted.

Default: false

PID_ZOMBIE_DOWN

If a process goes zombie, should it be considered as "down"?

Default: true

PID_LOGGING

If enabled, Centova Cast will log detailed process control and monitoring information to its event log to aid in debugging process control problems.

Default: false

THROTTLE_RESTART_ATTEMPTS

Configures the maximum number of times Centova Cast will attempt to restart a failed server/source application within a 30-minute period before throttling the restart attempts. Throttling failed restarts reduces server load and avoids mailbombing users/admins with restart notification emails.

Default: 3

APP_STARTUP_WAIT

Configures the number of microseconds to wait after starting a server/source application before checking to see if it exited unexpectedly.

This should be set high enough to give the application a chance to bail if something is wrong (such as a configuration file error or port conflict) but not so high as to cause unnecessarily long delays in the web interface.

Default: 500000

Log Processing

LOGPROCESS_MAX_RESUME

At the end of a log processing job, Centova Cast makes note of any listener sessions which appear to still be in progress, and saves them to be reloaded at the beginning of the next log processing job. Due to the way ShoutCast logs its sessions, in some very rare cases the end of a session may never be detected. This setting caps the number of sessions that may be resumed, ensuring that "endless sessions" do not remain endless forever.

Default: 2000

LOG_SLEEP_INTERVAL

Specifies the number of log lines after which Centova Cast will pause log processing to give the system load a chance to subside.

Log processing can be a CPU- and disk-intensive task, and on heavily-loaded servers you may want to reduce this value to limit the speed at which logs are processed and thereby reduce the system load.

Default: 500000

LOG_SLEEP_DURATION

Specifies the duration (in microseconds) for which Centova Cast will pause the log processing job.

Log processing can be a CPU- and disk-intensive task, and on heavily-loaded servers you may want to increase this value to limit the speed at which logs are processed and thereby reduce the system load.

Default: 100000

SMTP options

SMTP_CONNECT_TIMEOUT

Specifies the maximum amount of time (in seconds) to wait for a successful connection to the configured SMTP server. If a connection is not established in this time period, the email is discarded.

Default: 10

Daemon connectivity

RPC_CONNECT_TIMEOUT

Configures the timeout (in seconds) for the web interface to connect to cc-control. This should be kept as low as possible to avoid unnecessary delays in the event of a cc-control outage.

Default: 10

RPC_READ_TIMEOUT

Configures how long (in seconds) the web interface should wait for cc-control to process most commands. If cc-control takes longer than this to return a result, the web interface will assume something went wrong and throw a socket error.

Default: 60

RPC_LONG_READ_TIMEOUT

Configures how long (in seconds) the web interface should wait for cc-control to process disk-intensive commands, such as recursive filesystem operations, which may take awhile to complete. If your disks are slow, or your users have extremely large media libraries, you may need to increase this.

Default: 300

Compatibility features

FIX_SCTRANS_TITLES

sc_trans v1.x does not support ID3 tags; instead, it displays a mangled version of the MP3's filename as the track title. This results in the mangled filename being displayed in the Recent Tracks lists, the Now Playing widget,and other areas of Centova Cast.

Enabling this option causes Centova Cast to try to determine which song the filename corresponds to, and replace it with the actual artist/track name in the Recent Tracks list, Now Playing widget, and other areas of Centova Cast.

A better solution is to simply not use sc_trans v1.x.

Default: true

Application-assigned values

CRYPTO_KEY

Assigns a key for internal cryptography in Centova Cast. This value should be set once at installation and then never changed; typically it is set automatically by the Centova Cast installer. Changing this value may lead to loss of account/configuration data.

Default: (randomly generated at installation time)

USE_WEB_PROXY

Indicates to Centova Cast whether or not the port 80 proxy has been enabled on this server. Do not change this setting directly, as doing so will not enable or disable the proxy in itself. Instead, run:

/usr/local/centovacast/sbin/setproxy [on|off]

Default: false