Configuration Reference #

Example minimal working configuration cometmq.yaml:

database:
  data_dir: "/var/lib/cometmq"

listeners:
  - name: "plain"
    port: 5672

admin:
  bind: "0.0.0.0"
  port: 15672
  
acl:
  default_policy: "allow"

Configuration File #

By default, searches for cometmq.yaml in the current directory. Can be overridden with --config <path>.

Settings #

Database #

• data_dir (string, required) — directory for WAL files and snapshots
• wal_segment_size (uint, default 268435456) — WAL segment size in bytes
• wal_segment_count (uint, default 64) — number of segments in rotation
• auto_snapshot_after_ops (uint, default 10000) — create snapshot after N operations

Listeners #

Array of AMQP listeners. Each listener contains:

• name (string, required) — unique name
• port (uint16, required) — TCP port for binding
• host (string, default "0.0.0.0") — bind address
• tls (bool, default false) — enable TLS
• cert_path (string) — path to TLS certificate, if tls = true
• key_path (string) — path to TLS key, if tls = true

Admin #

HTTP Admin API server:

• bind (string, default "0.0.0.0") — admin HTTP bind address
• port (uint16, default 15672) — admin HTTP port

Heartbeat #

Heartbeat intervals for AMQP connections:

• server_interval (duration, default "30s") — server sends heartbeat every N
• timeout (duration, default "60s") — connection considered dead after missing heartbeat

ACL #

Access control:

• default_policy (enum: allow|deny) — default policy for undefined actions
• file_path (string, optional) — path to ACL file for monitoring changes

Quota #

Disk space limit management:

• policy (enum: none|warn|block) — action when limit exceeded
• limit_bytes (uint64) — disk usage limit in bytes

Flow Control #

Flow management and memory signals:

• memory_high_watermark_bytes (uint64, default 1073741824) — memory high watermark (1GB)
• disk_free_limit_bytes (uint64, default 1073741824) — minimum free disk space (1GB)

Metrics #

Metrics export:

• prometheus_listen (string, optional) — address:port for Prometheus metrics export

Full Configuration Example #

database:
  data_dir: "/var/lib/cometmq"
  wal_segment_size: 268435456
  wal_segment_count: 64
  auto_snapshot_after_ops: 10000

listeners:
  - name: "plain"
    host: "0.0.0.0"
    port: 5672
  - name: "tls"
    host: "0.0.0.0"
    port: 5671
    tls: true
    cert_path: "/etc/ssl/certs/cometmq.crt"
    key_path: "/etc/ssl/private/cometmq.key"

admin:
  bind: "0.0.0.0"
  port: 15672

heartbeat:
  server_interval: "30s"
  timeout: "60s"

acl:
  default_policy: "allow"
  file_path: "/etc/cometmq/acl.yaml"

quota:
  policy: "warn"
  limit_bytes: 10737418240

flow:
  memory_high_watermark_bytes: 2147483648
  disk_free_limit_bytes: 2147483648

metrics:
  prometheus_listen: "127.0.0.1:9090"

Running #

Run with configuration:

cometmq-broker --config /etc/cometmq/cometmq.yaml

Or use default cometmq.yaml from working directory:

cometmq-broker

• permissions (list) — set of vhost access rules:
  • vhost (string, regex allowed in code validation) — virtual host.
  • configure (regex string) — allowed objects for configuration operations (declare/delete).
  • write (regex string) — allowed objects for publishing.
  • read (regex string) — allowed objects for consuming.

Section vhosts #

• name (string) — virtual host identifier. Root is /. Multiple entries can be listed.

Section flow (memory and disk management) #

• high_gb (int) — memory high watermark (GiB). Above triggers memory alarm and connection.blocked.
• low_gb (int, optional) — memory low watermark (GiB) to clear alarm (hysteresis). If not set: 75% of high_gb.
• bytes_high_wm / bytes_low_wm (int, bytes, optional) — alternative byte thresholds (used if *_gb not set).
• disk_min_free_gb (int) — minimum required free disk space (GiB); below blocks persistent publishes.
• disk_min_free_bytes (int, optional) — byte alternative.

Section durable (message journal / WAL) #

• path (path) — directory for WAL segments.
• segment_mb (int) — single segment size (MiB); rotation on reach.
• flush_mode (enum: always | every_n | interval_ms) — fsync/flush strategy:
  • always — max durability, min performance.
  • every_n — fsync every N writes (see flush_every_n).
  • interval_ms — fsync on timer (see flush_interval_ms).
• flush_interval_ms (int, ms) — sync interval for interval_ms mode.
• flush_every_n (int) — write count between fsync for every_n mode.
• ack_flush_every_n (int) — periodic flush (no fsync) of ack bitmap after N acks.
• ack_fsync_on_full (bool) — fsync when segment fully ACKed.
• quota_bytes (int) — persistent backlog limit (bytes).
• quota_policy (enum: block | reject | reject-dlx) — action on overflow:
  • block — publisher confirms delayed until below threshold.
  • reject — immediate Basic.Nack without blocking.
  • reject-dlx — route to DLX with x-death{reason="quota"}, send Basic.Ack to publisher.
• segment_max_messages (int) — message threshold for segment rotation.
• partial_compaction_threshold (float 0..1) — minimum "garbage" fraction (ACKed messages) to trigger partial compaction.
• partial_compaction_interval_secs (int) — background compaction check interval (seconds).
• partial_compaction_min_reclaim_ratio (float) — minimum ratio of reclaimed bytes to segment size.
• partial_compaction_min_reclaim_bytes (int) — minimum reclaimed bytes.
• remap_max_entries (int) — remap entries limit for selected messages.

Section meta #

• path (path) — metadata storage directory (users, ACL, vhosts, durable declarations, etc.) for future clustering layer.

Parameter x_death_max_entries #

• (int) — limit of x-death history entries in message properties (latest-first). Controls metadata size and noise during redeliveries / DLX.

Section logs (logging configuration) #

• level (string, default info) — log level: trace, debug, info, warn, error.
• format (string, default json) — log output format:
  • json — structured JSON (for log aggregators: ELK, Loki, etc.).
  • plain — human-readable text format.

Example:

logs:
  level: debug
  format: plain

Application: level and format applied at startup. Changes require broker restart.

Applying Changes #

Most parameters require broker restart. Planned partial hot-reload for security.users and flow thresholds.

Minimal Configuration (no TLS or durable) #

network:
  bind: 0.0.0.0
  port: 5672
admin:
  bind: 0.0.0.0
  port: 15672
security:
  users:
    - username: admin
      password_hash: "<bcrypt>"
      permissions:
        - vhost: "/"
          configure: ".*"
          write: ".*"
          read: ".*"
vhosts:
  - name: "/"
logs:
  level: info
  format: json

Security Notes #

• Use TLS (network.tls section) in production, especially with external access.
• EXTERNAL authentication requires client_ca_path and proper certificates.
• Always store passwords as bcrypt hashes.

Flow and Memory Diagnostics #

Parameters in flow affect backpressure (connection.blocked). Choose thresholds based on available memory and load profile. Ensure disk_min_free_gb doesn't conflict with system alerts.

Next Steps #

• AMQP Basics
• CLI Reference
• Feature Matrix