Icecast Server/Events

Events

Overview

Icecast 2.5.x features an event subsystem. This subsystem is used to deliver information on certain events that happen within the server to backends. In it's nature it is very similar to the auth subsystem. However in contrast to the auth subsystem it cannot modify the server state in any way. This makes it much more performant at the cost of slightly less usecases. Events in the event subsystem are inherently delivered asynchronously. Therefore they may arrive at some handler in any order. However information regarding their causality is preserved via their data.

Configuration

Event subsystem backends are configured via <event />s inside of a <event-bindings />. <event-bindings /> can be used inside:

• <icecast /> (global headers)
• <mount />

<event-bindings /> has no properties itself. <event /> may contain <option />s with backend specific options. It will also use the following properties:

Property	Required	Type	Default	Description
type	yes	Backend name	none	The name of the backend to use.
trigger	yes	list of event names	none	A comma separated list of event names to deliver to this backend. The list may include * as wildcard after the first dash. Also entries can be prefixed using ! to negatively match them.

List of events

event	Context	Description
icecast-start	Global	Emitted when Icecast has been started up initially.
icecast-stop	Global	Emitted as part of Icecast's shutdown.
icecast-active	Global	Emitted when Icecast is active (has sources connected).
icecast-idle	Global	Emitted when Icecast is in idle (no sources connected).
source-connect	Source	Emitted when a source enters running state.
source-disconnect	Source	Emitted when a source is shut down.
source-flags-changed	Source	Emitted when a source experiences changes of it's flags. This might be for internal and external reasons.
source-listener-attach	Source	Emitted when a listener has been attached to a source. Note: experimental.
source-listeners-changed	Source	Emitted when the number of listeners changed. Note: experimental.
source-listeners-is-zero	Source	Same as source-listeners-changed but only emitted when the listener count is now zero. Note: experimental.
format-metadata-changed	Source	Emitted whenever the metadata on the format level changes.
dumpfile-opened	Source	Emitted when a dumpfile was just opened. At the time this is emitted any operations on the dumpfile as per the operating systems specification on open files are allowed. This usually includes renaming the file and moving it between directories on the same volume.
dumpfile-closed	Source	Emitted when a dumpfile is closed. Note: At this point Icecast knows hardly anything about the dumpfile anymore. So not all information is available to handlers of this event. Any operation should be done via dumpfile-opened whenever possible.
dumpfile-error	Source	Emitted when a dumpfile cannot be opened for any reason. See also dumpfile-opened.

Backends

exec

The exec backend is used to start local executables. As this comes with many per-operating system and deployment specific restrictions it is generally best avoided. The url backend is often a better alternative.

Options

Option	Required	Type	Default	Description
executable	Yes	path	none	Full path to the executable to be started
default_arguments	no	enum	default	Style of default arguments to be passed. One of: default, no_defaults, uri, uri_and_trigger, or legacy

In addition options with no name but type="argument" can be added. The values of those options are passed to the executable as arguments after the options passed as per default_arguments.

Styles of default arguments

Style	Arguments	Notes
default	-	Currently same as legacy.
no_defaults	none	No arguments are passed. Data is still accessible via environment.
uri	mount point	Only the mount point is passed as argument.
uri_and_trigger	mount point, trigger	The mount point followed by the name of the event that is delivered is passed.
legacy	[mount point]	Only the mount point is passed. If the mount point is not set for this event the argument is skipped.

Environment

Icecast will set the following environment:

Variable	Status	Availability	Notes
ICECAST_VERSION	stable	always	Version string of Icecast
ICECAST_HOSTNAME	stable	always	Hostname of Icecast as given in the config
ICECAST_ADMIN	stable	always	Admin context of Icecast as given in the config
ICECAST_LOGDIR	stable	always	Log directory of Icecast as given in the config
EVENT_TRIGGER	stable	always	The trigger for this event
EVENT_URI	stable	sometimes	URI (absolute or relative to this instance) the event happened on
SOURCE_ACTION	deprecated	always	Old name for EVENT_TRIGGER
SOURCE_MEDIA_TYPE	stable	sometimes	The Media-Type of the stream the source provides
SOURCE_INSTANCE	stable	sometimes	The instance of the source (UUID)
SOURCE_MOUNTPOINT	stable	sometimes	The mount point of the source
SOURCE_PUBLIC	stable	sometimes	Whether or not the mount is configured as public (true or false)
SROUCE_HIDDEN	stable	sometimes	Whether or not the mount is configured as hidden (true or false)
CLIENT_IP	stable	sometimes	The IP-Address of the client that caused the event
CLIENT_ROLE	stable	sometimes	The role of the client that caused the event
CLIENT_USERNAME	stable	sometimes	The username of the client that caused the event
CLIENT_USERAGENT	stable	sometimes	The user agent string of the client that caused the event
CLIENT_ID	stable	sometimes	The ID of the client that caused the event (integer)
CLIENT_CONNECTION_TIME	experimental	sometimes
CLIENT_ADMIN_COMMAND	experimental	sometimes	ID of the admin command the client accesses as causing the event
MOUNT_NAME	stable	sometimes	The name of the mount as per config
MOUNT_DESCRIPTION	stable	sometimes	The description of the mount as per config
MOUNT_URL	stable	sometimes	The URL (website) of the mount as per config
MOUNT_GENRE	stable	sometimes	The genre of the mount as per config
DUMPFILE_FILENAME	stable	sometimes	The filename used by Icecast to operate on a dump file (relative to Icecast's cwd)

log

The log backend writes events into the standard error.log. The main use for this is to debug and check configuration.

Options

Option	Required	Type	Default	Description
prefix	no	string	Event	A prefix to be used in the logfile. Can be used to easily grep(1) for the lines.
level	no	log level	information	The level at which to log the events.

url

This backend is used to deliver the event to some backend server (normally via HTTP). It is very similar to the auth subsystem's url backend.

Options

Option	Required	Type	Default	Description
username	no	username	none	Username used to login to the backend.
password	no	password	none	Password used to login to the backend.
url	Yes	URL	none	URL used to deliver the events to
action	no	string	name of the event	Value for the action-parameter sent as part of backend requests. When no value is given the name of the event is used.
legacy	no	boolean	true	Whether or not the new style is used for the parameters.