Configuration Reference - Mcaster1DNAS Documentation

Overview

This comprehensive reference documents all configuration options for Mcaster1DNAS v2.5.1-rc1. The server supports both YAML and XML configuration formats, with YAML being the recommended format going forward.

XML Configuration Deprecated: While XML configuration is still supported in v2.5.1-rc1, it will be deprecated in future releases. We strongly recommend using YAML configuration for all new deployments. YAML is more readable, easier to maintain, and supports modern configuration patterns.

Live Configuration Reload: Mcaster1DNAS v2.5.1-rc1 supports live configuration reloading via the admin interface. Access http://yourserver:8000/admin/reloadconfig to apply configuration changes without restarting the server. Note that some settings require a full restart to take effect.

Complete YAML Configuration Example

This is a comprehensive example showing all available configuration options in YAML format for Mcaster1DNAS v2.5.1-rc1.

# Mcaster1DNAS v2.5.1-rc1 Configuration (YAML)
# Complete example with all available options

server:
  hostname: stream.example.com
  location: Earth
  admin: admin@example.com
  server_id: Mcaster1DNAS v2.5.1-rc1
  fileserve: true

limits:
  clients: 800                  # Maximum concurrent connections
  sources: 10                   # Maximum source clients
  max_listeners: 700            # Maximum listeners (distinct from clients)
  queue_size: 512000            # Client queue size in bytes
  header_timeout: 15            # Header timeout in seconds
  source_timeout: 10            # Source timeout in seconds
  burst_size: 65536             # Or use "4s" for time-based

authentication:
  source_password: hackme
  relay_user: relay
  relay_password: hackme
  admin_user: admin
  admin_password: hackme

listen:
  - port: 8000
    bind_address: 0.0.0.0
  - port: 8001
    bind_address: 0.0.0.0
    shoutcast_mount: /live

ssl:
  enabled: true
  certificate: /etc/ssl/certs/server.pem
  private_key: /etc/ssl/private/key.pem
  ca_file: /etc/ssl/certs/ca-bundle.pem
  listen:
    - port: 8443
      bind_address: 0.0.0.0

paths:
  basedir: /usr/share/mcaster1dnas
  logdir: /var/log/mcaster1
  webroot: /usr/share/mcaster1dnas/web
  adminroot: /usr/share/mcaster1dnas/admin
  pidfile: /var/run/mcaster1.pid
  mime_types: /etc/mime.types

logging:
  loglevel: 3                   # 4=Debug, 3=Info, 2=Warn, 1=Error
  access_log: access.log
  error_log: error.log
  playlist_log: playlist.log
  log_archive: true
  log_size: 100M

yp:
  directories:
    - url: http://dir.xiph.org/cgi-bin/yp-cgi
      timeout: 15

relay:
  max_redirect_slaves: 5
  master:
    server: 192.168.1.11
    port: 8001
    username: relay
    password: hackme
    update_interval: 120
    redirect: true

mount:
  - path: /stream
    stream_name: "My Radio Station"
    stream_description: "The best music 24/7"
    stream_url: https://example.com
    genre: Rock
    bitrate: 128
    max_listeners: 100
    public: true
    fallback_mount: /backup
    burst_size: 65536
    authentication:
      type: htpasswd
      filename: /etc/mcaster1/users.htpasswd
      allow_duplicate_users: false

Server Settings

Global server identification and behavior settings.

hostname

The public hostname or IP address of your server. Used for generating stream URLs and YP directory listings. Example: stream.example.com

location

Geographic location of the server for informational purposes. Example: "New York, USA"

admin

Administrator email address displayed in server statistics and YP directories. Example: admin@example.com

server_id

Server identification string. Default is "Mcaster1DNAS v2.5.1-rc1" but can be customized.

fileserve

Enable static file serving from the webroot directory. Set to true/false (YAML) or 1/0 (XML).

Limits and Thresholds

Server-wide limits that control resource usage and connection management. These settings help prevent runaway resource consumption and ensure server stability.

clients

Maximum total concurrent connections to the server. This includes listeners, source clients, admin requests, and static file requests. Set higher than expected listener count to allow for overhead. Default: 800. Relay connections are not counted against this limit.

sources

Maximum number of source clients (encoders) allowed to connect simultaneously. Default: 2.

max_listeners

Maximum number of listeners allowed across all mountpoints. This is separate from the clients limit to prevent other connection types from being blocked. Default: No limit.

queue_size

Maximum size in bytes of the internal queue for each listener. If network congestion causes a listener's queue to exceed this size, the listener is disconnected. Default: 512000 (500KB).

header_timeout

Maximum time in seconds to wait for HTTP headers after a connection is established. Default: 15.

source_timeout

Maximum time in seconds a source connection can be idle before being disconnected. Default: 10.

burst_size

Amount of data sent immediately to new listeners to fill their player buffer. Can be specified in bytes (e.g., 65536) or seconds (e.g., "4s"). The time-based format automatically adjusts for different bitrates. Default: 65536 bytes (64KB).

Authentication

Server-wide authentication credentials for sources, relays, and administration.

source_password

Default password for source clients connecting with username "source". Can be overridden per-mountpoint.

relay_user / relay_password

Credentials used by slave servers to authenticate when requesting the list of streams to relay from this master server. Default username: "relay".

admin_user / admin_password

Credentials for accessing all admin functions including statistics, web interface, and server control.

Listen Sockets

Configure network interfaces and ports where Mcaster1DNAS accepts connections. Multiple listen sockets can be defined for different purposes.

# YAML format
listen:
  - port: 8000
    bind_address: 0.0.0.0       # Listen on all interfaces
  - port: 8001
    bind_address: 127.0.0.1     # Listen only on localhost
    shoutcast_mount: /live      # Mount for Shoutcast source clients

port

TCP port number to listen on. Standard streaming port is 8000.

bind_address

Optional IP address to bind to. Use 0.0.0.0 for all interfaces, 127.0.0.1 for localhost only, or a specific interface IP. Omit to bind to all interfaces.

shoutcast_mount

Mountpoint path for Shoutcast DSP source clients connecting to this port. Shoutcast sources require two sequential ports (this port and port+1).

SSL/TLS Configuration

Enable HTTPS encryption for streams and admin interface. Mcaster1DNAS v2.5.1-rc1 includes enhanced SSL/TLS support with modern cipher suites.

# YAML format
ssl:
  enabled: true
  certificate: /etc/ssl/certs/server.pem
  private_key: /etc/ssl/private/key.pem
  ca_file: /etc/ssl/certs/ca-bundle.pem
  listen:
    - port: 8443
      bind_address: 0.0.0.0

enabled

Enable or disable SSL/TLS support. Set to true/false.

certificate

Path to PEM-formatted server certificate. May include certificate bundle.

private_key

Path to PEM-formatted private key file.

ca_file

Path to Certificate Authority bundle. Often provided by OS SSL library but can be overridden.

File Paths

Directory and file locations used by Mcaster1DNAS. All paths should not end with a slash.

basedir

Base directory used for chroot security (Unix/Linux only). All other paths become relative to this when chroot is enabled.

logdir

Directory where log files (access.log, error.log) are written. Default: ./logs

webroot

Directory for static files served by the fileserver. Stream playlist files and static content are served from here. Default: ./web

adminroot

Directory containing XSLT stylesheets and resources for the web-based admin interface. Default: ./admin

pidfile

File where the process ID is written at startup and removed at shutdown. Useful for init scripts and process management. Default: ./mcaster1.pid

mime_types

Path to MIME types file for file serving. Typically /etc/mime.types on Unix systems. Not usually required as common types are built-in.

Logging Configuration

Mcaster1DNAS v2.5.1-rc1 includes enhanced logging capabilities with automatic log rotation and configurable verbosity levels.

# YAML format
logging:
  loglevel: 3                   # 4=Debug, 3=Info, 2=Warn, 1=Error
  access_log: access.log
  error_log: error.log
  playlist_log: playlist.log    # Optional metadata logging
  log_archive: true             # Append timestamp to rotated logs
  log_size: 100M                # Rotate when log reaches this size

loglevel

Logging verbosity: 4=Debug (very verbose), 3=Info (recommended), 2=Warn (problems only), 1=Error (critical only). Debug level can generate very large log files.

access_log

Filename for HTTP access log. Records all listener connections, admin requests, and file serves. Relative to logdir.

error_log

Filename for error and informational log. All server messages are written here. Relative to logdir.

playlist_log

Optional log file recording metadata updates for each mountpoint. Format is pipe-delimited. Useful for royalty reporting and analytics.

log_archive

When true, append timestamp to rotated logs (logfile.TIMESTAMP). When false, rotate to logfile.old (overwriting previous backup). Default: false.

log_size

Maximum log file size before automatic rotation. Use format like "100M" for megabytes or "1G" for gigabytes. Set to 0 to disable automatic rotation.

YP Directory Settings

Configure YP (Yellow Pages) directory servers for public stream listing. Mcaster1DNAS v2.5.1-rc1 includes enhanced YP logging for troubleshooting registration issues.

# YAML format
yp:
  directories:
    - url: http://dir.xiph.org/cgi-bin/yp-cgi
      timeout: 15
    - url: http://dir2.xiph.org/cgi-bin/yp-cgi
      timeout: 15

url

Directory server endpoint URL. Provided by the directory service operator. Multiple directories can be configured for redundancy.

timeout

Maximum time in seconds to wait for directory server response. Default: 15. Increase if directory is slow or remote.

Relay Configuration

Configure stream relaying for load distribution and geographic redundancy. See the Relay Documentation for detailed examples.

Master-Slave Relay (YAML)

relay:
  max_redirect_slaves: 5
  master:
    server: 192.168.1.11
    port: 8001
    username: relay
    password: hackme
    update_interval: 120
    redirect: true

Single-Broadcast Relay (YAML)

relay:
  relays:
    - server: 192.168.1.11
      port: 8001
      mount: /example.ogg
      local_mount: /different.ogg
      username: relay
      password: hackme

Mount-Specific Settings

Per-mountpoint configuration overrides. Define settings for specific streams including authentication, limits, metadata, and fallback behavior.

# YAML format
mount:
  - path: /premium
    stream_name: "Premium Stream"
    stream_description: "High quality audio"
    stream_url: https://example.com
    genre: Jazz
    bitrate: 320
    max_listeners: 100
    public: true
    fallback_mount: /backup
    fallback_when_full: true
    burst_size: 65536
    authentication:
      type: htpasswd
      filename: /etc/mcaster1/users.htpasswd
      allow_duplicate_users: false
    on_connect: /usr/local/bin/stream-start
    on_disconnect: /usr/local/bin/stream-end

path

Mountpoint path (e.g., /stream, /live.ogg). Supports wildcards (e.g., /*.mp3) to apply settings to multiple mounts matching a pattern.

stream_name

Stream title displayed in players and YP directories.

stream_description

Detailed description for YP directories and statistics.

stream_url

Website URL associated with the stream.

genre

Stream category/genre for YP directories (e.g., Rock, Jazz, Talk).

bitrate

Stream bitrate in kbps. Used for YP listings and statistics.

max_listeners

Maximum concurrent listeners for this mountpoint. Overrides server-wide limit.

public

Control YP directory listing: true=force listing, false=prevent listing, omit=let source decide. Default: Source client controls via ice-public header.

fallback_mount

Mountpoint to transfer listeners to when source disconnects. Can be another mountpoint or a static file in webroot. Enables multi-level fallback cascading.

fallback_when_full

When true, redirect new listeners to fallback mount when max_listeners is reached. Useful for overflow handling.

authentication

Listener authentication configuration. See Listener Authentication for htpasswd and URL authentication details.

on_connect / on_disconnect

Shell scripts executed when source connects/disconnects. Script receives mountpoint path as parameter. Useful for automation and notifications. Not available on Windows.

Additional Resources

Basic Setup Guide - Get started with your first configuration
Relay Configuration - Detailed relay examples
Listener Authentication - Secure your streams
YP Directory Listing - Publish to stream directories
Admin Interface - Manage your server

Best Practices: Use YAML configuration for new deployments. Keep your configuration under version control. Test configuration changes with /admin/reloadconfig before full restart. Document custom settings with comments for future maintenance.