YAML Configuration Reference

Overview

Mcaster1DNAS supports YAML configuration files in addition to XML, providing a modern, human-readable alternative for server configuration. The server automatically detects whether a config file is XML or YAML — no flag or extension change required.

Features

Automatic Format Detection — YAML document markers (---), XML tags (<?xml, <mcaster1>), or key-value patterns (key: value)
Full Feature Parity — 100% of XML config features available in YAML
Comments — Native inline comment support with #
Four templates included — full, minimal, shoutcast-compat, and advanced

Feature Parity Checklist

✔ Multi-port listeners (HTTP, HTTPS, IPv6, Shoutcast compatibility)
✔ Multiple mount points with wildcard support
✔ Authentication (htpasswd, URL-based, command-based)
✔ Relays with multi-host failover
✔ Fallback streams with bitrate limits
✔ Bandwidth limiting and burst control
✔ HTTP header customization
✔ YP directory support
✔ Logging configuration (access, error, playlist)
✔ Security (chroot, changeowner)
✔ Aliases and redirects
✔ Master/slave replication

Build Instructions

./autogen.sh
./configure --prefix=/var/www/mcaster1.com/mcaster1dnas/build --with-yaml --with-openssl
make -j4
make install

Verify YAML support:

./build/bin/mcaster1 -v
# Should show: Mcaster1DNAS 2.5.0

Usage

# Start with YAML config (auto-detected)
./build/bin/mcaster1 -c /path/to/config.yaml

# Start with XML config (also auto-detected)
./build/bin/mcaster1 -c /path/to/config.xml

YAML Syntax Examples

Basic Server Settings

---
location: "Earth"
admin: "admin@example.com"
hostname: "radio.example.com"
fileserve: true

Authentication

authentication:
  source-password: "source_pass"
  admin-user: "admin"
  admin-password: "admin_pass"
  relay-user: "relay"
  relay-password: "relay_pass"

Limits

limits:
  clients: 100
  sources: 10
  workers: 2
  queue-size: 524288
  burst-size: 65536
  client-timeout: 30
  song-history-limit: 25   # tracks kept in memory for /songdata API (0 = unlimited)

Multi-Port Listeners

listen-sockets:
  # HTTP plain
  - port: 9330
    bind-address: "0.0.0.0"
    ssl: false

  # HTTPS/TLS only
  - port: 9443
    bind-address: "0.0.0.0"
    ssl: true

  # Shoutcast compatibility
  - port: 8001
    shoutcast-compat: true

  # IPv6
  - port: 9330
    bind-address: "::"

Paths

paths:
  basedir:         "/usr/local/mcaster1dnas"
  logdir:          "/var/log/mcaster1dnas"
  webroot:         "/usr/local/mcaster1dnas/web"
  adminroot:       "/usr/local/mcaster1dnas/admin"
  pidfile:         "/var/run/mcaster1dnas.pid"
  ssl-certificate: "/etc/ssl/mcaster1dnas.pem"
  aliases:
    - source: "/"
      destination: "/status.xsl"

Mount Point with Authentication

mounts:
  - mount-name: "/premium.mp3"
    max-listeners: 100
    authentication:
      type: "htpasswd"
      options:
        - name: "filename"
          value: "/path/to/users.htpasswd"
    fallback:
      mount: "/backup.mp3"
      rate: 128000
    public: true
    stream-name: "Premium Stream"
    genre: "Various"

ICY 2.2 Mount Metadata

mounts:
  - mount-name: "/live"
    mount-type: "live"
    max-listeners: 100
    public: 1
    stream-name: "My Live Radio"
    stream-description: "Live electronic music"
    genre: "Electronic"
    bitrate: "128"
    icy-dj-handle: "@djname"
    icy-show-title: "The Evening Show"
    icy-requests-enabled: true
    icy-requests-url: "https://myradio.com/request"
    icy-chat-url: "https://discord.gg/myradio"
    icy-donate-url: "https://ko-fi.com/myradio"

Relay with Failover

relays:
  - local-mount: "/relay.mp3"
    on-demand: true
    masters:
      - ip: "primary.example.com"
        port: 8000
        mount: "/live.mp3"
        priority: 1
      - ip: "backup.example.com"
        port: 8000
        mount: "/live.mp3"
        ssl: true
        priority: 2
    username: "relay"
    password: "relaypass"

Logging

logging:
  accesslog:
    name: "access.log"
    archive: true
  errorlog:
    name: "error.log"
    level: "debug"
    archive: true
  playlistlog:
    name: "playlist.log"
    archive: true
  logsize: 10000
  logarchive: true

HTTP Headers (CORS)

http-headers:
  - name: "Access-Control-Allow-Origin"
    value: "*"
  - name: "Access-Control-Allow-Methods"
    value: "GET, OPTIONS"

XML vs YAML Comparison

XML	YAML
`<listen-socket> <port>8000</port> <bind-address>0.0.0.0</bind-address> <ssl>0</ssl> </listen-socket>`	`listen-sockets: - port: 8000 bind-address: "0.0.0.0" ssl: false`

Migration from XML

Use mcaster1-production.yaml as a template
Copy your XML values to corresponding YAML keys
Test with: ./build/bin/mcaster1 -c config.yaml

Validation & Troubleshooting

The server reports parsing errors on startup:

ERROR: YAML parse error in config.yaml at line 42: mapping values are not allowed here

Test config without starting:

./build/bin/mcaster1 -c config.yaml 2&>1 | head -20
# Look for "server reading configuration from config.yaml"

Common Issues

Error	Solution
YAML configuration detected but YAML support not compiled in	Recompile with `--with-yaml` flag
libyaml development files not found	Install libyaml-dev: `apt-get install libyaml-dev`
YAML parse error: mapping values not allowed	Check indentation — use spaces, not tabs
YAML parse error: unexpected character	Quote strings containing `:` `#` `@` or other special chars
Windows: access violation in libyaml	Fixed in v2.5.1-beta.1 — config is now read into memory before passing to yaml.dll

Dependencies

Required for YAML support:

libyaml-dev ≥ 0.1.7 (Debian/Ubuntu: apt-get install libyaml-dev)
yaml-devel ≥ 0.1.7 (RHEL/CentOS: yum install libyaml-devel)
Windows: vcpkg install libyaml (x64-windows triplet)

Without YAML support (--with-yaml omitted), the server still works fully with XML configs.

Performance

YAML parsing is slightly slower than XML (negligible for config files — parsed once at startup). Once loaded, runtime performance is identical to XML.

Future Enhancements (v2.6.0)

JSON configuration support
Config validation tool (mcaster1-validate-config)
Config converter (mcaster1-xml2yaml, mcaster1-yaml2xml)
Environment variable substitution in YAML
Include directives for modular configs