Configuration Reference

rabbitmq-backup uses a single YAML configuration file for both backup and restore operations. The mode field determines which sections are required.

Top-Level Structure

mode: backup | restore       # Required
backup_id: "string"          # Required
source: { ... }              # Required for backup
target: { ... }              # Required for restore
storage: { ... }             # Required
backup: { ... }              # Optional (backup mode)
restore: { ... }             # Optional (restore mode)
offset_storage: { ... }      # Optional
metrics: { ... }             # Optional

---

mode

Field	Type	Required	Values
mode	string	Yes	backup, restore

Determines the operating mode. Controls which other top-level sections are required.

---

backup_id

Field	Type	Required	Example
backup_id	string	Yes	"rabbitmq-backup-001"

Unique identifier for this backup. Used as the top-level directory/prefix in storage. All segments and the manifest are stored under {backup_id}/.

---

source

Source RabbitMQ connection configuration. Required for mode: backup.

source:
  amqp_url: "amqp://user:pass@host:5672/%2f"
  management_url: "http://host:15672"
  management_username: guest
  management_password: guest
  stream_port: 5552
  tls:
    enabled: false
    ca_cert: /path/to/ca.pem
    client_cert: /path/to/client.pem
    client_key: /path/to/client-key.pem
  queues:
    include: ["orders-*"]
    exclude: ["*-dead-letter"]
    vhosts: ["/"]
    types: [classic, quorum]
    min_messages: 0

Fields

Field	Type	Required	Default	Description
amqp_url	string	Yes	--	AMQP 0-9-1 connection URL. Format: amqp://user:pass@host:port/vhost. Use %2f for the default vhost /.
management_url	string	Yes	--	RabbitMQ Management HTTP API base URL.
management_username	string	Yes	--	Management API username.
management_password	string	Yes	--	Management API password. Supports ${ENV_VAR} interpolation.
stream_port	u16	No	5552	RabbitMQ Stream Protocol port. Only used when backup.stream_enabled: true.
tls	object	No	null	TLS configuration for AMQP and Stream Protocol connections.
queues	object	No	null (all queues)	Queue selection criteria. If omitted, all queues are backed up.

source.tls

Field	Type	Required	Default	Description
enabled	bool	No	false	Enable TLS for AMQP connections.
ca_cert	string (path)	No	null	Path to CA certificate PEM file.
client_cert	string (path)	No	null	Path to client certificate PEM file (for mutual TLS).
client_key	string (path)	No	null	Path to client private key PEM file (for mutual TLS).

source.queues

Field	Type	Required	Default	Description
include	list of strings	No	[] (all)	Queue name patterns to include. Supports glob syntax (*, ?).
exclude	list of strings	No	[]	Queue name patterns to exclude. Applied after include.
vhosts	list of strings	No	[] (all)	Virtual hosts to include.
types	list of strings	No	[] (all)	Queue types to include: classic, quorum, stream.
min_messages	u64	No	0	Skip queues with fewer messages than this threshold.

---

target

Target RabbitMQ connection configuration. Required for mode: restore.

target:
  amqp_url: "amqp://user:pass@host:5672/%2f"
  management_url: "http://host:15672"
  management_username: guest
  management_password: guest

Fields

Field	Type	Required	Default	Description
amqp_url	string	Yes	--	AMQP 0-9-1 connection URL for the target cluster.
management_url	string	No	null	Management API URL. Required if restore.restore_definitions: true or restore.create_missing_queues: true.
management_username	string	No	null	Management API username. Required with management_url.
management_password	string	No	null	Management API password. Required with management_url.

---

storage

Storage backend configuration. Required. Uses a tagged enum -- the backend field determines which other fields are expected.

Filesystem

storage:
  backend: filesystem
  path: /var/lib/rabbitmq-backup/data

Field	Type	Required	Description
backend	string	Yes	Must be filesystem.
path	string (path)	Yes	Base directory path for storing backups. Created if it does not exist.

S3 / S3-Compatible

storage:
  backend: s3
  bucket: rabbitmq-backups
  region: us-east-1
  endpoint: http://localhost:9000    # For MinIO/Ceph
  access_key: AKIA...
  secret_key: secret...
  prefix: cluster-prod/
  path_style: true                   # Required for MinIO/Ceph
  allow_http: true                   # Required for non-TLS endpoints

Field	Type	Required	Default	Description
backend	string	Yes	--	Must be s3.
bucket	string	Yes	--	S3 bucket name.
region	string	No	null	AWS region (e.g. us-east-1). Falls back to AWS_DEFAULT_REGION.
endpoint	string	No	null	Custom endpoint URL. Required for S3-compatible services (MinIO, Ceph RGW, DigitalOcean Spaces).
access_key	string	No	null	AWS access key ID. Falls back to AWS_ACCESS_KEY_ID env var.
secret_key	string	No	null	AWS secret access key. Falls back to AWS_SECRET_ACCESS_KEY env var.
prefix	string	No	null	Key prefix prepended to all storage operations. Useful for organizing multiple clusters in one bucket.
path_style	bool	No	false	Use path-style requests instead of virtual hosted-style. Required for MinIO, Ceph RGW.
allow_http	bool	No	false	Allow HTTP (non-TLS) connections. Required when endpoint uses http://.

Azure Blob Storage

storage:
  backend: azure
  account_name: myaccount
  container_name: rabbitmq-backups
  account_key: "base64key..."          # Option 1: Account key
  sas_token: "?sv=2022-11-02&..."      # Option 2: SAS token
  prefix: cluster-prod/
  endpoint: https://myaccount.blob.core.usgovcloudapi.net  # Sovereign clouds
  use_workload_identity: true          # Option 3: AKS Workload Identity
  client_id: "guid"                    # Option 4: Service principal
  tenant_id: "guid"
  client_secret: "secret"

Field	Type	Required	Default	Description
backend	string	Yes	--	Must be azure.
account_name	string	Yes	--	Azure storage account name.
container_name	string	Yes	--	Blob container name.
account_key	string	No	null	Storage account key. Falls back to AZURE_STORAGE_KEY or AZURE_STORAGE_ACCOUNT_KEY.
prefix	string	No	null	Key prefix for all operations.
endpoint	string	No	null	Custom endpoint URL for sovereign/government clouds.
use_workload_identity	bool	No	null	Enable AKS Workload Identity authentication. Auto-detected from AZURE_FEDERATED_TOKEN_FILE.
client_id	string	No	null	Azure AD client ID for service principal authentication. Falls back to AZURE_CLIENT_ID.
tenant_id	string	No	null	Azure AD tenant ID. Falls back to AZURE_TENANT_ID.
client_secret	string	No	null	Azure AD client secret. Falls back to AZURE_CLIENT_SECRET.
sas_token	string	No	null	Shared Access Signature token. Falls back to AZURE_STORAGE_SAS_TOKEN.

Authentication priority: account_key > sas_token > service principal (client_id + tenant_id + client_secret) > workload identity > DefaultAzureCredential chain.

Google Cloud Storage

storage:
  backend: gcs
  bucket: rabbitmq-backups
  service_account_path: /path/to/sa-key.json
  prefix: cluster-prod/

Field	Type	Required	Default	Description
backend	string	Yes	--	Must be gcs.
bucket	string	Yes	--	GCS bucket name.
service_account_path	string	No	null	Path to service account JSON key file. Falls back to GOOGLE_APPLICATION_CREDENTIALS env var, then Application Default Credentials.
prefix	string	No	null	Key prefix for all operations.

Memory (Testing Only)

storage:
  backend: memory

In-memory storage for unit and integration testing. Data is not persisted.

---

backup

Backup-specific options. All fields have defaults and the entire section is optional.

backup:
  segment_max_bytes: 134217728
  segment_max_interval_ms: 60000
  compression: zstd
  compression_level: 3
  prefetch_count: 100
  requeue_strategy: cancel
  max_concurrent_queues: 4
  checkpoint_interval_secs: 5
  sync_interval_secs: 30
  include_definitions: true
  stop_at_current_depth: true
  stream_enabled: false

Fields

Field	Type	Default	Description
segment_max_bytes	u64	134217728 (128 MB)	Maximum uncompressed segment size in bytes before rotation.
segment_max_interval_ms	u64	60000 (60 sec)	Maximum time interval in milliseconds before segment rotation.
compression	string	zstd	Compression algorithm: zstd, lz4, or none.
compression_level	i32	3	Compression level. For zstd: 1-22 (higher = smaller but slower). Ignored for lz4 and none.
prefetch_count	u16	100	AMQP QoS prefetch count. Number of messages the broker will deliver before waiting for acknowledgment. Set to 0 for unlimited (default with cancel strategy).
requeue_strategy	string	cancel	Strategy for returning messages to the queue after reading. See Requeue Strategies.
max_concurrent_queues	usize	4	Maximum number of queues backed up in parallel. Each queue uses its own AMQP connection.
checkpoint_interval_secs	u64	5	Interval in seconds between checkpoint writes to the offset store.
sync_interval_secs	u64	30	Interval in seconds between checkpoint syncs to remote storage.
include_definitions	bool	true	Include definitions export (vhosts, exchanges, queues, bindings, users, policies) in the backup.
stop_at_current_depth	bool	true	One-shot mode: stop after backing up the current queue depth. If false, the backup runs continuously (useful for streaming backups).
stream_enabled	bool	false	Enable native Stream Protocol for x-queue-type: stream queues. Requires the RabbitMQ stream plugin and source.stream_port.

Requeue Strategies

Strategy	AMQP Method	Description	Trade-offs
cancel	basic.consume then basic.cancel	Default and recommended. Consumes messages without acknowledging, then cancels the consumer. All unacked messages are automatically requeued by the broker.	Messages have redelivered=true after backup. Fastest for large queues.
nack	basic.get + basic.nack(requeue=true)	Gets each message then explicitly nacks with requeue.	Messages requeued individually. Higher per-message overhead.
reject	basic.reject(requeue=true)	Rejects each message with requeue.	Similar to nack but only handles one message at a time.
get	basic.get (pull mode) + nack	Pull-based one-at-a-time retrieval.	Slowest. Useful for very small queues or debugging.

---

restore

Restore-specific options. All fields have defaults and the entire section is optional.

restore:
  time_window_start: 1712700000000
  time_window_end: 1712800000000
  queue_mapping:
    orders: orders-restored
    payments: payments-v2
  vhost_mapping:
    production: staging
  exchange_mapping:
    events: events-restored
  publish_mode: exchange
  publisher_confirms: true
  max_concurrent_queues: 4
  produce_batch_size: 100
  rate_limit_messages_per_sec: 0
  restore_definitions: true
  definitions_dry_run: false
  definitions_selection:
    vhosts: []
    queues: []
    exchanges: []
  create_missing_queues: false
  checkpoint_state: ./restore-checkpoint.db
  checkpoint_interval_secs: 60
  dry_run: false

Fields

Field	Type	Default	Description
time_window_start	i64 (epoch ms)	null	PITR start timestamp. Only messages with backed_up_at >= time_window_start are restored.
time_window_end	i64 (epoch ms)	null	PITR end timestamp. Only messages with backed_up_at <= time_window_end are restored.
queue_mapping	map (string -> string)	{}	Queue name remapping. Keys are source queue names, values are target queue names. Unmapped queues keep their original names.
vhost_mapping	map (string -> string)	{}	Vhost remapping.
exchange_mapping	map (string -> string)	{}	Exchange remapping for publish_mode: exchange.
publish_mode	string	exchange	Message publish mode. See Publish Modes.
publisher_confirms	bool	true	Enable AMQP publisher confirms for reliable delivery.
max_concurrent_queues	usize	4	Maximum number of queues restored in parallel.
produce_batch_size	usize	100	Batch size for publishing messages. Larger batches improve throughput at the cost of memory.
rate_limit_messages_per_sec	u64	0	Rate limit in messages per second. 0 means unlimited.
restore_definitions	bool	true	Restore definitions (topology) before restoring messages. Requires target.management_url.
definitions_dry_run	bool	false	Validate definitions without actually importing them.
definitions_selection	object	empty	Optional partial definitions restore selector. Empty means import all backed-up definitions. See Definitions Selection.
create_missing_queues	bool	false	Auto-create missing target queues before message restore. Applies to publish_mode: direct-to-queue and requires target Management API credentials.
checkpoint_state	string (path)	null	Path to checkpoint SQLite database for resumable restores. Completed queues are skipped on rerun; partial queues resume after the last checkpointed record.
checkpoint_interval_secs	u64	60	Interval in seconds between checkpoint writes during restore.
dry_run	bool	false	Validate the restore plan without publishing any messages. Prints a summary and exits.

Publish Modes

Mode	Description
exchange	Default. Publish to the original exchange with the original routing key. Respects exchange_mapping for remapping. Messages are routed through the exchange topology.
direct-to-queue	Publish directly to the target queue via the default exchange (routing key = queue name). Bypasses exchange routing.

Definitions Selection

definitions_selection lets you restore only part of the backed-up RabbitMQ topology before message replay:

restore:
  restore_definitions: true
  definitions_selection:
    vhosts:
      - "production"
    queues:
      - "orders"
    exchanges:
      - "orders-exchange"

Field	Type	Default	Description
vhosts	list of strings	[]	Vhosts to restore. If set without queues or exchanges, all queues, exchanges, bindings, permissions, policies, and parameters in those vhosts are restored.
queues	list of strings	[]	Queue names to restore. The filter also keeps required source exchanges and bindings that route to the selected queues.
exchanges	list of strings	[]	Exchange names to restore. Bindings are kept when both their source and destination are selected or required by selected queues.

Validation is strict: a selected vhost, queue, or exchange that does not exist in the backup definitions fails the restore before importing anything. Empty selection preserves the default full definitions import.

Create Missing Queues

When create_missing_queues: true and publish_mode: direct-to-queue, restore checks each target queue through the Management API and declares it if missing:

target:
  amqp_url: "amqp://guest:guest@localhost:5672/%2f"
  management_url: "http://localhost:15672"
  management_username: guest
  management_password: guest

restore:
  publish_mode: direct-to-queue
  create_missing_queues: true

Created queues use safe restore defaults:

Source manifest queue type	Created target arguments
classic	{}
quorum	{"x-queue-type": "quorum"}
stream	{"x-queue-type": "stream"}

For publish_mode: exchange, queue creation is not enough to guarantee routing. In that mode, restore expects the target exchange and binding topology to exist, usually through restore_definitions: true.

---

offset_storage

Checkpoint/offset storage configuration for resumable backups.

offset_storage:
  backend: sqlite
  db_path: ./offsets.db
  s3_key: state/offsets.db
  sync_interval_secs: 30

Fields

Field	Type	Default	Description
backend	string	sqlite	Storage backend: sqlite or memory.
db_path	string (path)	./offsets.db	Path to the SQLite database file for checkpoint persistence.
s3_key	string	null	Remote storage key for syncing the checkpoint database. Enables checkpoint persistence across restarts.
sync_interval_secs	u64	30	Interval in seconds between syncing the local checkpoint to remote storage.

Backup checkpoints record completed queue segments and stream offsets. On rerun with the same backup_id, completed queues or streams reuse existing verified segment files instead of rewriting them. For remote storage, set s3_key so the SQLite checkpoint database is synced to object storage.

---

metrics

Prometheus metrics endpoint configuration.

metrics:
  enabled: true
  port: 8080
  bind_address: "0.0.0.0"
  path: /metrics

Fields

Field	Type	Default	Description
enabled	bool	true	Enable the metrics HTTP server.
port	u16	8080	TCP port for the metrics HTTP server.
bind_address	string	"0.0.0.0"	Bind address for the metrics HTTP server.
path	string	"/metrics"	HTTP path for the Prometheus metrics endpoint.

The metrics server also serves:

• GET /health or GET /healthz -- returns {"status":"ok"} (JSON)
• GET / -- HTML index page with links to /metrics and /health

---

Full Example: Backup to S3

mode: backup
backup_id: "prod-daily-2025-04-10"

source:
  amqp_url: "amqp://rmq-user:${RMQ_PASSWORD}@rabbitmq.prod.internal:5672/%2f"
  management_url: "https://rabbitmq.prod.internal:15672"
  management_username: admin
  management_password: "${RMQ_MGMT_PASSWORD}"
  stream_port: 5552
  tls:
    enabled: true
    ca_cert: /etc/ssl/certs/internal-ca.pem
  queues:
    include:
      - "orders-*"
      - "payments-*"
      - "events-*"
    exclude:
      - "*-dead-letter"
      - "*-retry-*"
    vhosts:
      - "/"
      - "production"
    types:
      - classic
      - quorum
      - stream
    min_messages: 1

storage:
  backend: s3
  bucket: company-rabbitmq-backups
  region: eu-west-1
  prefix: prod-cluster/

backup:
  compression: zstd
  compression_level: 3
  prefetch_count: 200
  requeue_strategy: cancel
  max_concurrent_queues: 8
  segment_max_bytes: 268435456   # 256 MB
  segment_max_interval_ms: 120000 # 2 minutes
  include_definitions: true
  stop_at_current_depth: true
  stream_enabled: true

offset_storage:
  backend: sqlite
  db_path: /var/lib/rabbitmq-backup/offsets.db
  s3_key: state/offsets.db
  sync_interval_secs: 30

metrics:
  enabled: true
  port: 9090
  bind_address: "0.0.0.0"
  path: /metrics

Full Example: Restore with PITR

mode: restore
backup_id: "prod-daily-2025-04-10"

target:
  amqp_url: "amqp://rmq-user:${RMQ_PASSWORD}@rabbitmq.staging.internal:5672/%2f"
  management_url: "https://rabbitmq.staging.internal:15672"
  management_username: admin
  management_password: "${RMQ_MGMT_PASSWORD}"

storage:
  backend: s3
  bucket: company-rabbitmq-backups
  region: eu-west-1
  prefix: prod-cluster/

restore:
  # Restore only messages from 10:00 to 14:00 UTC on April 10
  time_window_start: 1712739600000
  time_window_end: 1712754000000
  queue_mapping:
    orders-prod: orders-staging
    payments-prod: payments-staging
  vhost_mapping:
    production: staging
  publish_mode: exchange
  publisher_confirms: true
  max_concurrent_queues: 4
  produce_batch_size: 50
  rate_limit_messages_per_sec: 1000
  restore_definitions: true
  definitions_dry_run: false
  definitions_selection:
    vhosts: ["production"]
    queues: ["orders-prod"]
    exchanges: []
  create_missing_queues: false
  checkpoint_state: ./restore-checkpoint.db
  dry_run: false