View source for Icecast Server/Events

= Events =
<div class="boilerplate metadata" style="background-color: #fee; margin: 0 1em; padding: 0 10px; border: 1px solid #aaa;">
'''Icecast 2.5.x page'''

This page discusses the topic in context of Icecast 2.5.x. The situation for 2.4.x might be different.
</div>

== 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 <code><<nowiki />event /></code>s inside of a <code><<nowiki />event-bindings /></code>. <code><<nowiki />event-bindings /></code> can be used inside:
* <code><<nowiki />icecast /></code> (global headers)
* <code><<nowiki />mount /></code>

<code><<nowiki />event-bindings /></code> has no properties itself.
<code><<nowiki />event /></code> may contain <code><<nowiki />option /></code>s with backend specific options. It will also use the following properties:
{| class="wikitable"
! Property !! Required !! Type !! Default !! Description
|-
| <code>type</code> || yes || Backend name || ''none'' || The name of the backend to use.
|-
| <code>trigger</code> || yes || list of event names || ''none'' || A comma separated list of event names to deliver to this backend. The list may include <code>*</code> as wildcard after the first dash. Also entries can be prefixed using <code>!</code> to negatively match them.
|}

== List of events ==

{| class="wikitable"
! event !! Context !! Description
|-
| <code>icecast-start</code>  || Global || Emitted when Icecast has been started up initially.
|-
| <code>icecast-stop</code>   || Global || Emitted as part of Icecast's shutdown.
|-
| <code>icecast-active</code> || Global || Emitted when Icecast is active (has sources connected).
|-
| <code>icecast-idle</code>   || Global || Emitted when Icecast is in idle (no sources connected).
|-
| <code>source-connect</code> || Source || Emitted when a source enters running state.
|-
| <code>source-disconnect</code> || Source || Emitted when a source is shut down.
|-
| <code>source-flags-changed</code> || Source || Emitted when a source experiences changes of it's flags. This might be for internal and external reasons.
|-''
| <code>source-listener-attach</code> || Source || Emitted when a listener has been attached to a source. '''Note:''' experimental.
|-
| <code>source-listeners-changed</code> || Source || Emitted when the number of listeners changed. '''Note:''' experimental.
|-
| <code>source-listeners-is-zero</code> || Source || Same as <code>source-listeners-changed</code> but only emitted when the listener count is now zero. '''Note:''' experimental.
|-
| <code>format-metadata-changed</code> || Source || Emitted whenever the metadata on the format level changes.
|-
| <code>dumpfile-opened</code> || 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.
|-
| <code>dumpfile-closed</code> || 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 <code>dumpfile-opened</code> whenever possible.
|-
| <code>dumpfile-error</code> || Source || Emitted when a dumpfile cannot be opened for any reason. See also <code>dumpfile-opened</code>.
|}

== Backends ==
=== <code>exec</code> ===
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 <code>url</code> backend is often a better alternative.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>executable</code> || Yes || path || ''none'' || Full path to the executable to be started
|-
| <code>default_arguments</code> || no || enum || <code>default</code> || Style of default arguments to be passed. One of: <code>default</code>, <code>no_defaults</code>, <code>uri</code>, <code>uri_and_trigger</code>, or <code>legacy</code>
|}

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

==== Styles of default arguments ====
{| class="wikitable"
! Style !! Arguments || Notes
|-
| <code>default</code> || - || Currently same as <code>legacy</code>.
|-
| <code>no_defaults</code> || ''none'' || No arguments are passed. Data is still accessible via environment.
|-
| <code>uri</code> || mount point || Only the mount point is passed as argument.
|-
| <code>uri_and_trigger</code> || mount point, trigger || The mount point followed by the name of the event that is delivered is passed.
|-
| <code>legacy</code> || [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:
{| class="wikitable"
! Variable !! Status !! Availability !! Notes
|-
| <code>ICECAST_VERSION</code> || stable || always || Version string of Icecast
|-
| <code>ICECAST_HOSTNAME</code> || stable || always || Hostname of Icecast as given in the config
|-
| <code>ICECAST_ADMIN</code> || stable || always || Admin context of Icecast as given in the config
|-
| <code>ICECAST_LOGDIR</code> || stable || always || Log directory of Icecast as given in the config
|-
| <code>EVENT_TRIGGER</code> || stable || always || The trigger for this event
|-
| <code>EVENT_URI</code> || stable || sometimes || URI (absolute or relative to this instance) the event happened on
|-
| <code>SOURCE_ACTION</code> || deprecated || always || Old name for <code>EVENT_TRIGGER</code>
|-
| <code>SOURCE_MEDIA_TYPE</code> || stable || sometimes || The Media-Type of the stream the source provides
|-
| <code>SOURCE_INSTANCE</code> || stable || sometimes || The instance of the source (UUID)
|-
| <code>SOURCE_MOUNTPOINT</code> || stable || sometimes || The mount point of the source
|-
| <code>SOURCE_PUBLIC</code> || stable || sometimes || Whether or not the mount is configured as public (<code>true</code> or <code>false</code>)
|-
| <code>SROUCE_HIDDEN</code> || stable || sometimes || Whether or not the mount is configured as hidden (<code>true</code> or <code>false</code>)
|-
| <code>CLIENT_IP</code> || stable || sometimes || The IP-Address of the client that caused the event
|-
| <code>CLIENT_ROLE</code> || stable || sometimes || The role of the client that caused the event
|-
| <code>CLIENT_USERNAME</code> || stable || sometimes || The username of the client that caused the event
|-
| <code>CLIENT_USERAGENT</code> || stable || sometimes || The user agent string of the client that caused the event
|-
| <code>CLIENT_ID</code> || stable || sometimes || The ID of the client that caused the event (integer)
|-
| <code>CLIENT_CONNECTION_TIME</code> || experimental || sometimes ||
|-
| <code>CLIENT_ADMIN_COMMAND</code> || experimental || sometimes || ID of the admin command the client accesses as causing the event
|-
| <code>MOUNT_NAME</code> || stable || sometimes || The name of the mount as per config
|-
| <code>MOUNT_DESCRIPTION</code> || stable || sometimes || The description of the mount as per config
|-
| <code>MOUNT_URL</code> || stable || sometimes || The URL (website) of the mount as per config
|-
| <code>MOUNT_GENRE</code> || stable || sometimes || The genre of the mount as per config
|-
| <code>DUMPFILE_FILENAME</code> || stable || sometimes || The filename used by Icecast to operate on a dump file (relative to Icecast's cwd)
|}

=== <code>log</code> ===
The <code>log</code> backend writes events into the standard <code>error.log</code>. The main use for this is to debug and check configuration.
==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>prefix</code> || no || string || <code>Event</code> || A prefix to be used in the logfile. Can be used to easily grep(1) for the lines.
|-
| <code>level</code> || no || log level || <code>information</code> || The level at which to log the events.
|}

=== <code>url</code> ===
This backend is used to deliver the event to some backend server (normally via HTTP). It is very similar to the auth subsystem's <code>url</code> backend.
==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>username</code> || no || username || ''none'' || Username used to login to the backend.
|-
| <code>password</code> || no || password || ''none'' || Password used to login to the backend.
|-
| <code>url</code> || Yes || URL || ''none'' || URL used to deliver the events to
|-
| <code>action</code> || no || string || ''name of the event'' || Value for the <code>action</code>-parameter sent as part of backend requests. When no value is given the name of the event is used.
|-
| <code>legacy</code> || no || boolean || ''true'' || Whether or not the new style is used for the parameters.
|-
|}