Configuration Guide

Configuration Priority

Monibuca uses a multi-layer configuration system with priority from highest to lowest:

Runtime (API dynamic modification) > Database (persisted) > Env (environment variables) > File (config file) > Default (default values)

Priority	Source	Description
Highest	Runtime	Modified at runtime via HTTP API
High	Database	Persisted configuration loaded from database
Medium	Environment	Environment variables M7S_{PLUGIN}_{FIELD}
Low	File	config.yaml configuration file
Lowest	Default	Default values defined in code

Higher-priority configurations override lower-priority configurations with the same key.

YAML Configuration File

Complete Example

# =============================================
# Monibuca V6 Configuration File
# =============================================

# Global configuration - inherited by all plugins
global:
  # Log level: trace, debug, info, warn, error
  loglevel: info

  # Disable all plugins (each plugin must manually set enable: true)
  disableall: false

  # Public IP (for NAT traversal, leave empty for auto-detection)
  publicip: ""
  publicipv6: ""

  # Authentication toggle
  enableauth: false

  # HTTP service configuration (shared by all HTTP-based plugins)
  http:
    listenaddr: ":8180"
    cors: true
    corsorigins:
      - "*"
    readtimeout: 30
    writetimeout: 30
    idletimeout: 120

  # TCP service configuration (gRPC, etc.)
  tcp:
    listenaddr: ":50051"

  # Default publish configuration
  publish:
    pubtimeout: 10        # Publish timeout (seconds)
    waitclosetimeout: 0   # Wait-close timeout (seconds)
    delayclosetime: 0     # Delay close time (seconds)
    kick: false           # Whether to kick streams with the same name
    ringsize: 256         # RingBuffer size
    maxfps: 0             # Maximum frame rate limit (0 = unlimited)

  # Default subscribe configuration
  subscribe:
    subtimeout: 10        # Subscribe timeout (seconds)
    waittimeout: 10       # Wait-for-stream timeout (seconds)
    buffertime: 2000      # Buffer time (milliseconds)
    internalbuffersize: 10
    subvideo: true        # Whether to subscribe to video
    subaudio: true        # Whether to subscribe to audio

  # Database configuration
  db:
    dsn: "sqlite:m7s.db?mode=rwc"

  # Admin panel
  admin:
    enablelogin: false
    username: admin
    password: admin

# =============================================
# Protocol Plugins
# =============================================

# RTMP protocol
rtmp:
  enable: true
  tcp:
    listenaddr: ":1935"
    readbuffersize: 65536
    writebuffersize: 65536
    nodelay: true
  chunksize: 4096

# RTSP protocol
rtsp:
  enable: true
  tcp:
    listenaddr: ":8554"
  udpportstart: 10000
  udpportend: 20000

# HLS protocol
hls:
  enable: true
  segmentduration: 6
  maxsegments: 5
  outputdir: "./hls"
  writetodisk: true

# WebRTC protocol (WHIP/WHEP)
webrtc:
  enable: true
  portrange: "udp:9000-9100"
  publicip: ""

# SRT protocol
srt:
  enable: true
  listenaddr: ":6000"
  latency_ms: 120
  # passphrase: "your_passphrase"  # Optional, 10-79 characters

# GB28181 national standard protocol
gb28181:
  enable: false
  sip:
    - domain: "3402000000"
      domain_id: "34020000002000000001"
      lan_ip: "0.0.0.0"
      wan_ip: ""
      port: 5060
      network: udp
  rtp_port_min: 10000
  rtp_port_max: 20000
  heartbeat_timeout: 60
  register_timeout: 300

# =============================================
# Feature Plugins
# =============================================

# Log rotation
logrotate:
  enable: false
  logdir: "./logs"
  filenamepattern: "monibuca-%Y%m%d.log"
  maxsize: 104857600    # 100MB
  maxbackups: 7
  maxage: 30
  compress: true
  rotationinterval: daily

# Room system
room:
  enable: true
  app_name: "room"
  max_users_per_room: 100
  ping_interval: 30
  ping_timeout: 60

Configuration Inheritance

Global publish and subscribe configurations are inherited by all plugins. Plugins can override these values:

global:
  publish:
    ringsize: 256      # Global default RingBuffer size

rtmp:
  enable: true
  publish:
    ringsize: 512      # RTMP plugin uses a larger RingBuffer

Stream Auth Configuration

Minimal setup:

global:
  enableauth: true
  publish:
    key: "your-publish-key"
  subscribe:
    key: "your-subscribe-key"

For full details (signature algorithm, parameters, protocol coverage, custom auth handlers), see:

• Advanced: Stream Authentication

Environment Variables

Environment variables follow the M7S_{PLUGIN}_{FIELD} naming convention, with all letters uppercase and nested fields separated by underscores.

Naming Convention

M7S_{PLUGIN_NAME}_{FIELD_PATH}

Configuration	Environment Variable
global.loglevel	M7S_GLOBAL_LOGLEVEL
global.http.listenaddr	M7S_GLOBAL_HTTP_LISTENADDR
rtmp.tcp.listenaddr	M7S_RTMP_TCP_LISTENADDR
rtmp.tcp.nodelay	M7S_RTMP_TCP_NODELAY
global.publish.ringsize	M7S_GLOBAL_PUBLISH_RINGSIZE
webrtc.iceservers	M7S_WEBRTC_ICESERVERS

Array Values

Array-type values are separated by commas:

# ICE server list
export M7S_WEBRTC_ICESERVERS="stun:stun1.example.com,stun:stun2.example.com"

# CORS allowed origins
export M7S_GLOBAL_HTTP_CORSORIGINS="https://a.com,https://b.com"

Typical Usage

# Development environment
M7S_GLOBAL_LOGLEVEL=debug ./monibuca -c config.yaml

# Production environment - override ports
M7S_RTMP_TCP_LISTENADDR=":11935" \
M7S_GLOBAL_HTTP_LISTENADDR=":80" \
./monibuca -c config.yaml

Database Persistence

Monibuca supports persisting configurations to a database, ensuring configurations are preserved across restarts.

Supported Databases

Database	DSN Format	Feature Flag
SQLite	sqlite:m7s.db?mode=rwc	Built-in by default
MySQL	mysql://user:pass@host:3306/db	mysql
PostgreSQL	postgres://user:pass@host:5432/db	postgres

Configuration

global:
  db:
    # SQLite (default, zero configuration)
    dsn: "sqlite:m7s.db?mode=rwc"

    # MySQL
    # dsn: "mysql://root:password@localhost:3306/monibuca"

    # PostgreSQL
    # dsn: "postgres://postgres:password@localhost:5432/monibuca"

Compile-time Enablement

To use MySQL or PostgreSQL, use the corresponding pre-compiled version or Docker image:

# Docker image includes MySQL and PostgreSQL support by default
docker run -d \
  -e M7S_GLOBAL_DB_DSN="mysql://root:password@host:3306/monibuca" \
  langhuihui/monibuca:v6

HTTP API Dynamic Configuration

Configurations can be dynamically modified at runtime via HTTP API. Modified values have the highest priority.

Query Current Configuration

# Get global configuration
curl http://localhost:8180/api/config/global

# Get specific plugin configuration
curl http://localhost:8180/api/config/rtmp

Modify Configuration

# Modify plugin configuration
curl -X POST http://localhost:8180/api/config/rtmp \
  -H "Content-Type: application/json" \
  -d '{"chunksize": 8192}'

# Modify global configuration
curl -X POST http://localhost:8180/api/config/global \
  -H "Content-Type: application/json" \
  -d '{"loglevel": "debug"}'

Configuration Reload

Trigger a configuration file reload via API to apply the latest file configuration:

# Reload configuration
curl -X POST http://localhost:8180/api/config/reload

Important Notes

• Some configuration changes require restarting the corresponding service to take effect (e.g., listen ports)
• Configurations modified via API are automatically saved to the database if database persistence is enabled
• Without database persistence enabled, API-modified configurations will be lost after restart

Configuration Best Practices

Development Environment

global:
  loglevel: debug
  admin:
    enablelogin: false

rtmp:
  enable: true
  tcp:
    listenaddr: ":1935"

Production Environment

global:
  loglevel: warn
  enableauth: true
  http:
    listenaddr: ":8180"
    cors: true
    corsorigins:
      - "https://your-domain.com"
  publish:
    ringsize: 512
    kick: false
  subscribe:
    buffertime: 3000
  db:
    dsn: "postgres://user:pass@db-host:5432/monibuca"
  admin:
    enablelogin: true
    username: admin
    password: your_secure_password

rtmp:
  enable: true
  tcp:
    listenaddr: ":1935"

hls:
  enable: true
  segmentduration: 4
  maxsegments: 6

logrotate:
  enable: true
  logdir: "/var/log/monibuca"
  maxbackups: 30
  compress: true

Docker Compose Environment

docker-compose.yml

services:
  monibuca:
    image: langhuihui/monibuca:v6
    ports:
      - "8180:8180"
      - "8443:8443"
      - "1935:1935"
      - "8554:8554"
      - "50051:50051"
      - "6000:6000/udp"
      - "9000-9100:9000-9100/udp"
    volumes:
      - ./config.yaml:/etc/monibuca/config.yaml
      - ./data:/monibuca/data
    environment:
      - M7S_GLOBAL_LOGLEVEL=info
      - M7S_GLOBAL_PUBLICIP=your.public.ip
    restart: unless-stopped

---

For a deeper look at system architecture, see System Architecture.