Examples

This section includes two complete example configuration files for the Rocket Streaming Audio Server.

Remember that config files are passed to RSAS using the -c flag, like:

$ ./rsas -c myconfig.xml

Simple Example

This minimal example configures RSAS to listen on port 8000, and has a single mount configured at /example:

<icecast>
    <listen-socket>
        <port>8000</port>
        <bind-address>0.0.0.0</bind-address> <!-- listen on all interfaces -->
    </listen-socket>

    <mount>
        <mount-name>/example</mount-name>
        <username>source</username>
        <password>hackme</password>
    </mount>
</icecast>

Advanced Example ("The Kitchen Sink")

This comprehensive example uses every configuration option available in Rocket Streaming Audio Server.

Some notable features it demonstrates are:

Multiple listen sockets (listening on multiple ports)
Explicitly setting the number of worker threads
HLS enabled for all streams
Customizing the log path and log file names
A sophisticated fallback configuration:
- A primary /main mount, which falls back to:
- ... a fallback /backup mount, which falls back to:
- ... a relay mount at /relay, which falls back to:
- ... a looped audio file at /unavailable.mp3.
A wildcard mount that uses webhook source authentication to authenticate sources dynamically.
A premium mount that uses a webhook to authenticate listeners, and notify when they disconnect.
A relay mount which mirrors a stream from another server.
An HLS relay mount which mirrors an HLS stream from another RSAS server.
HTTPS:
- TLS configuration
- A second TLS certificate for an alternate domain (VHosts / SNI)

As a prerequisite, an unavailable.mp3 file is expected to be in /usr/share/rsas/webroot.

Here is the configuration for this advanced example:

<icecast>

    <listen-socket>
        <port>8000</port>
        <bind-address>0.0.0.0</bind-address> <!-- Listen on all interfaces -->
    </listen-socket>
    <!-- Multiple listen-sockets can be specified, to serve on multiple interfaces or ports. -->
    <listen-socket>
        <port>80</port>
        <bind-address>0.0.0.0</bind-address>
    </listen-socket>

    <!-- Let's enable HTTPS / TLS too -->
    <listen-socket>
        <port>443</port>
        <tls>1</tls>
        <!-- Optional: Add HSTS header to instruct browsers to only ever use HTTPS -->
        <custom-headers>
            <add-header name="Strict-Transport-Security" value="max-age=31536000; includeSubDomains" />
        </custom-headers>
    </listen-socket>


    <!-- Enable the Icecast-compatible status page and /status-json.xsl JSON endpoint -->
    <emulation>
        <icecast-status-page>1</icecast-status-page>
    </emulation>

    <!-- Set the hostname, required for HLS support -->
    <hostname>streams.example.com</hostname>

    <!-- You can set a custom base URL if there's a reverse proxy running in front of RSAS. Overrides the <hostname> -->
    <base-url>https://streams.example.com/rsas</base-url>

    <!-- You can add a version string that gets displayed in /heath, to track which config file is running -->
    <config-version>2021/08/05</config-version>

    <authentication>
        <!-- Optional admin password - can be used to authenticate as a source on mount, or used with the Icecast APIs -->
        <admin-password>adminhackme</admin-password>
        <!-- Optional password protection for /health endpoint -->
        <health-password>health</health-password>
    </authentication>

    <paths>
        <logdir>/var/log/rsas</logdir>          <!-- Log files are stored here -->
        <webroot>/usr/share/rsas/webroot</webroot>  <!-- Static files are served from here -->

        <!-- HTTPS / TLS certificate configuration -->
        <ssl-certificate>/etc/rsas/certs/fullchain.pem</ssl-certificate>
        <ssl-private-key>/etc/rsas/certs/privkey.pem</ssl-private-key>
        <ssl-dhparams>/etc/rsas/certs/dhparams.pem</ssl-dhparams>
        <!-- These are the default ciphers. You can omit this next line if you want the defaults. -->
        <ssl-allowed-ciphers>ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:
        ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:
        ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:
        ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:
        ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS</ssl-allowed-ciphers>

        <!-- Aliases allow you to remap URLs -->
        <alias source="/" dest="/main" />  <!-- Route listeners on / to the /main mount -->

    </paths>

    <!-- Add an extra TLS certificate for our alternate domain -->
    <vhosts>
        <vhost>
            <hostname>my-other-hostname.com</hostname>
            <ssl-certificate>le-test-certs/fullchain.pem</ssl-certificate>
            <ssl-private-key>le-test-certs/privkey.pem</ssl-private-key>
        </vhost>
    </vhosts>

    <limits>
        <!-- The number of threads to use. "auto" uses the number of logical cores. Set to 1 to disable multithreading. -->
        <workers>auto</workers>
        <clients>10000</clients> <!-- Max listeners in total -->
        <max-http-header-size>4096</max-http-header-size> <!-- Maximum HTTP request header length. We do not recommend changing this. -->
    </limits>

    <logging>
        <!-- Log rotation is automatic and can be configured here. These settings are the defaults, if not specified.-->
        <access>
            <filename>access.log</filename>
            <maxsize>10MB</maxsize>
            <maxlogs>10</maxlogs>
        </access>
        <error>
            <filename>error.log</filename>
            <maxsize>10MB</maxsize>
            <maxlogs>10</maxlogs>
        </error>
        <playlist>
            <filename>playlist.log</filename>
            <maxsize>10MB</maxsize>
            <maxlogs>10</maxlogs>
        </playlist>     
    </logging>


    <!-- HLS settings (global) -->
    <hls>
        <enabled>1</enabled>

        <!-- Optionally customize some HLS settings. We recommend omitting these and letting RSAS use the defaults. -->
        <max-segments-in-playlist>10</max-segments-in-playlist>
        <segment-size>64KB</segment-size>
        <!-- Use relative paths in M3U8 playlists. Default is absolute URLs. -->
        <relative-paths>1</relative-paths>
    </hls>

    <!-- Outbound HTTP proxy to use. Used when RSAS makes outbound HTTP requests. -->
    <http-proxy>
        <host>127.0.0.1</host>
        <port>3128</port>
        <username>foobar</username>
        <password>foobar</password>
    </http-proxy>


    <mount>
        <mount-name>/main</mount-name>
        <username>source</username>
        <password>hackme</password>
        <max-listeners>100</max-listeners>
        <fallback-mount>/fallback</fallback-mount>
        <fallback-override>1</fallback-override> <!-- Move listeners back when we come back online -->
        <fallback-when-full>1</fallback-when-full>
        <max-listener-duration>3600</max-listener-duration> <!-- Limit listeners to 1 hour sessions (in seconds) -->
        <hidden>1</hidden> <!-- Hide this mount from emulated Icecast status page -->        
        <health-password>health</health-password>  <!-- Optional mount-specific password for /<mount>/health endpoint.
                                                        Otherwise uses global health-password, if set. -->
        <hls>1</hls> <!-- Allow this stream to be served as HLS. Overrides global HLS setting. -->

        <!-- Ad Insertion -->
        <preroll>https://example.com/preroll.mp3</preroll> <!-- Play this audio file before the stream -->
        <!-- If preroll or postroll files are local, on disk, they must reside inside your webroot path and written as a relative path: -->
        <!-- eg. <preroll>local_jingle.mp3</preroll> -->
        <postroll>https://example.com/postroll.mp3</postroll> <!-- Play this audio file if the user exceeds the max-listener-duration -->
        <midroll-webhook>https://example.com/midroll-webhook</midroll-webhook> <!-- Fetch list of ads here when a midroll ad break is triggered by metadata or the Manage API. -->
        <default-midroll-title>Thank you for listening</default-midroll-title> <!-- Default metadata to display during an ad -->
    </mount>

    <!-- A fallback mount for /main, which itself falls back to a relay. -->
    <mount>
        <mount-name>/fallback</mount-name>
        <username>source</username>
        <password>hackme</password>
        <max-listeners>100</max-listeners>
        <fallback-mount>/relay</fallback-mount>
        <fallback-override>1</fallback-override>
    </mount>

    <!-- A relay mount. See the <relay> section below -->
    <mount>
        <mount-name>/relay</mount-name>
        <username>source</username>
        <password>hackme</password>
        <max-listeners>100</max-listeners>
        <fallback-mount>/unavailable.mp3</fallback-mount>
        <fallback-override>1</fallback-override>
    </mount>

    <!-- Relay configuration for the /relay mount -->
    <relay>
        <!-- We even follow 301 redirects here too, and HTTPS is also supported. -->
        <url>http://www.myotherserver.com:8000/mystream</url>
        <local-mount>/relay</local-mount>
        <on-demand>1</on-demand> <!-- On-demand: Start the relay only when a listener connects. Set to 0 for a persistent relay, which always stays connected or retries forever. -->
        <auto-stop>1</auto-stop> <!-- Stop the relay automatically when the last listener disconnects -->
    </relay>


    <!-- Looping Audio File Fallback -->
    <mount>
        <mount-name>/unavailable.mp3</mount-name>
        <username>source</username>
        <password>hackme</password>
        <max-listeners>100</max-listeners>
        <!-- Explicitly setting these parameters helps looped audio files work for new listeners -->
        <type>audio/mpeg</type>
        <bitrate>64</bitrate>
        <channels>2</channels>
        <samplerate>44100</samplerate>
    </mount>


    <!-- Wildcard mount with webhook source authentication (HTTPS works too!) -->
    <mount>
        <mount-name>/*</mount-name>
        <authentication type="url">
            <option name="auth_header" value="icecast-auth-user: 1"/>
            <option name="stream_auth" value="https://127.0.0.1:5000/icecast-source-auth"/>
        </authentication>
    </mount>

    <!-- A premium mount using listener webhook authentication, and notifies on listener disconnect -->
    <mount>
        <mount-name>/premium</mount-name>
        <authentication type="url">
            <option name="auth_header" value="icecast-auth-user: 1"/>
            <option name="listener_add" value="https://127.0.0.1:5000/listener-auth"/>
            <option name="listener_remove" value="https://127.0.0.1:5000/listener-auth"/>
            <!-- Pass some extra HTTP headers from the listener through to the webhook -->
            <option name="headers" value="authorization,x-forwarded-for"/>
            <option name="header_prefix" value="X-Passthrough-"/>
        </authentication>
    </mount>

    <!-- An HLS relay mount. See the <relay> section below -->
    <mount>
        <mount-name>/hls-relay</mount-name>
    </mount>

    <!-- HLS Relay configuration for the /hls-relay mount -->
    <relay>
        <!-- We even follow 301 redirects here too, and HTTPS is also supported. -->
        <url>http://www.myotherserver.com:8000/mystream</url>
        <local-mount>/relay</local-mount>
        <on-demand>1</on-demand>
        <!-- Relay the HLS playlist and segments from the upstream RSAS server -->
        <hls-relay>1</hls-relay>
    </relay>

</icecast>