Icecast Server/Events - Revision history

Phschafft: /* exec */ Added environment variable list

2023-07-29T09:15:03Z

exec: Added environment variable list

@@ Line 86: / Line 86: @@
 |-
 | <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.
 |}

Phschafft: /* List of events */ Fix: Corrected markup

2023-04-18T12:20:55Z

List of events: Fix: Corrected markup

← Older revision		Revision as of 12:20, 18 April 2023
Line 42:		Line 42:
	\|-		\|-
	\| <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-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-~~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-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>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>format-metadata-changed</code> \|\| Source \|\| Emitted whenever the metadata on the format level changes.
Line 53:		Line 53:
	\| <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-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-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>.		\| <code>dumpfile-error</code> \|\| Source \|\| Emitted when a dumpfile cannot be opened for any reason. See also <code>dumpfile-opened</code>.

Phschafft: /* List of events */ Update: Added experimental events

2023-04-18T12:20:03Z

List of events: Update: Added experimental events

← Older revision		Revision as of 12:20, 18 April 2023
Line 42:		Line 42:
	\|-		\|-
	\| <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-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>format-metadata-changed</code> \|\| Source \|\| Emitted whenever the metadata on the format level changes.

Phschafft: /* exec */ Feature: Added infos on the exec event backend

2023-04-18T10:17:50Z

exec: Feature: Added infos on the exec event backend

@@ Line 54: / Line 54: @@
 == Backends ==
 === <code>exec</code> ===
-TODO.
+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.
 === <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.

Phschafft: /* url */ Feature: Added infos on the url backend

2023-04-18T10:01:32Z

url: Feature: Added infos on the url backend

← Older revision		Revision as of 10:01, 18 April 2023
Line 67:		Line 67:

	=== <code>url</code> ===		=== <code>url</code> ===
	~~TODO~~.		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.
			\|-
			\|}

Phschafft: /* log */ Feature: Description of the log backend

2023-04-18T09:55:09Z

log: Feature: Description of the log backend

← Older revision		Revision as of 09:55, 18 April 2023
Line 56:		Line 56:
	TODO.		TODO.
	=== <code>log</code> ===		=== <code>log</code> ===
	~~TODO~~.		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> ===		=== <code>url</code> ===
	TODO.		TODO.

Phschafft: Update: Added basic list of backends

2023-04-18T09:34:56Z

Update: Added basic list of backends

← Older revision		Revision as of 09:34, 18 April 2023
Line 51:		Line 51:
	\| <code>dumpfile-error</code> \|\| Source \|\| Emitted when a dumpfile cannot be opened for any reason. See also <code>dumpfile-opened</code>.		\| <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> ===
			TODO.
			=== <code>log</code> ===
			TODO.
			=== <code>url</code> ===
			TODO.

Phschafft: /* Configuration */ Update: Added note on wildcards and negative matches

2023-04-18T09:31:59Z

Configuration: Update: Added note on wildcards and negative matches

← Older revision		Revision as of 09:31, 18 April 2023
Line 21:		Line 21:
	\| <code>type</code> \|\| yes \|\| Backend name \|\| ''none'' \|\| The name of the backend to use.		\| <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.		\| <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.
	\|}		\|}

Phschafft: /* Configuration */ Update: Added options

2023-04-18T09:17:23Z

Configuration: Update: Added options

@@ Line 13: / Line 13: @@
 * <code><<nowiki />icecast /></code> (global headers)
 * <code><<nowiki />mount /></code>
 == List of events ==

Phschafft: Feature: Added stub on event related tags.

2023-04-18T09:11:34Z

Feature: Added stub on event related tags.

← Older revision		Revision as of 09:11, 18 April 2023
Line 8:		Line 8:
	== Overview ==		== 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.		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>

	== List of events ==		== List of events ==