Website/content/docs/infrastructure/icecast/_index.md

97 lines
4 KiB
Markdown
Raw Normal View History

2024-02-26 18:02:48 +01:00
---
title: 'Icecast'
date: 2024-02-26T07:41:44+01:00
---
[Icecast](https://icecast.org/) is a streaming media server supporting open
standards such as the Ogg Vorbis[^1] container format. You can used it to create
an internet radio station or live streaming applications. My [streaming setup](streaming-setup/)
is based on Icecast and drives live streaming without 3rd party services.
{{< figure src="img/icecast-logo.svg" alt="Icecast logo" width="25%" >}}
## Basic setup
I refer to instructions found in the
[Icecast2 — UberLab 7 documentation](https://lab.uberspace.de/guide_icecast2)
and the official [Icecast docs](https://www.icecast.org/docs/icecast-trunk/). In
addition to the basic setup, some settings have to be changed for my needs.
## TLS setup
If you didn't use the UberLab guide, all Icecast access might be unencrypted!
2024-04-07 22:39:50 +02:00
You need to enable TLS[^2] manually by inserting [`<tls>1</tls>`](https://www.icecast.org/docs/icecast-trunk/config_file/#tcp-port-settings)
2024-02-26 18:02:48 +01:00
in the `<listen-socket>` block of the `icecast.xml` configuration file.
2024-04-07 22:39:50 +02:00
Additionally, specify a `<tls-certificate>` in the [`<path>`](https://www.icecast.org/docs/icecast-trunk/config_file/#path-settings)
2024-02-26 18:02:48 +01:00
block and provide a file containing the cert and private key in sequence at the
2024-04-07 22:39:50 +02:00
specified location. Finally, restart Icecast server to reload the new configuration.
2024-02-26 18:02:48 +01:00
{{< callout type="info" >}}
If Icecast refuses to start, increase the [logging level](#logging-level),
analyze the logfiles and check if it has been compiled against
[OpenSSL](https://www.openssl.org/).
{{< /callout >}}
## Fallback mount
Listeners can only play streams while a source client is streaming. In order to
offer static media while there's no source client connected, a [fallback mount](https://www.icecast.org/docs/icecast-trunk/config_file/#mount-specific-settings)
can be used. I edit the `icecast.xml` config file and insert:
```xml
<mount type="normal">
<mount-name>/stream.ogg</mount-name>
<fallback-mount>/file.ogg</fallback-mount>
<fallback-override>1</fallback-override>
<fallback-when-full>1</fallback-when-full>
<bitrate>192</bitrate>
<type>application/ogg</type>
<subtype>vorbis</subtype>
</mount>
```
Change `/file.ogg` to fit your needs. The provided file should have the same
encoding parameters (for example: 192 kbps CBR[^3]) to prevent listener dropouts and must exist in Icecast's webroot to be accessible. [Fileserving](https://www.icecast.org/docs/icecast-trunk/config_file/#general-settings)
must also be activated. (Enabled by default.)
## No-cache
Applications playing streams may automatically cache data. This behaviour can
lead to looping or aborting media when a fallback override
(source client connection) is happening. Using the following [HTTP headers](https://www.icecast.org/docs/icecast-trunk/config_file/#http-headers)
configuration in `icecast.xml` the caching can be disabled:
```xml
<http-headers>
<header name="Cache-control" value="no-cache, no-store, must-revalidate" />
<header name="Pragma" value="no-cache" />
<header name="Expires" value="0" />
</http-headers>
```
## Logging level
For a maximum privacy of the listeners log files need to be discarded. Icecast's [logging](https://www.icecast.org/docs/icecast-trunk/config_file/#logging-settings)
cannot be disabled, but written to a Null device[^4]. This can be done by
removing the standard log files `access.log` and `error.log` and creating
symbolic links as follows:
```bash
rm /var/log/icecast/access.log
rm /var/log/icecast/error.log
ln -s /dev/null /var/log/icecast/access.log
ln -s /dev/null /var/log/icecast/error.log
```
## Applications
{{< cards >}}
2024-02-29 15:41:18 +01:00
{{< card link="streaming-setup" title="Streaming setup" icon="play" >}}
{{< /cards >}}
2024-02-26 18:02:48 +01:00
2024-02-29 15:41:18 +01:00
[^1]: [Vorbis](https://en.wikipedia.org/wiki/Vorbis) in the Wikipedia
[^2]: [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security)
(TLS) in the Wikipedia
[^3]: [Constant bitrate](https://en.wikipedia.org/wiki/Constant_bitrate) (CBR)
in the Wikipedia
[^4]: [Null device](https://en.wikipedia.org/wiki/Null_device) in the Wikipedia