Definitions Management

RabbitMQ definitions include your cluster topology: vhosts, users, permissions, exchanges, queues, bindings, and policies. rabbitmq-backup can export and import definitions independently from message backup, making it a lightweight tool for topology management.

What Are Definitions?

Component	Description
Vhosts	Logical groupings for multi-tenancy
Users	Authentication credentials and tags
Permissions	Per-user, per-vhost access controls
Exchanges	Message routing points
Queues	Message storage endpoints
Bindings	Routes between exchanges and queues
Policies	HA, TTL, queue length limits, etc.
Parameters	Shovel, Federation, and custom parameters

Export Definitions

Export the full topology from a running RabbitMQ cluster:

rabbitmq-backup definitions-export \
  --config config.yaml \
  --output definitions.json

If you omit --output, the definitions are printed to stdout:

rabbitmq-backup definitions-export --config config.yaml > definitions.json

The config file only needs connection details:

config.yaml

mode: backup
backup_id: "definitions-only"

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

storage:
  backend: memory  # not used for definitions-only export

Exported File Format

The output is standard RabbitMQ definitions JSON, compatible with the Management API:

{
  "rabbit_version": "4.0.0",
  "rabbitmq_version": "4.0.0",
  "vhosts": [
    { "name": "/" }
  ],
  "users": [
    { "name": "guest", "password_hash": "...", "tags": ["administrator"] }
  ],
  "permissions": [...],
  "exchanges": [...],
  "queues": [...],
  "bindings": [...],
  "policies": [...]
}

Import Definitions

Import definitions to a target RabbitMQ cluster:

rabbitmq-backup definitions-import \
  --config target-config.yaml \
  --input definitions.json

target-config.yaml

mode: restore
backup_id: "definitions-import"

target:
  amqp_url: "amqp://admin:password@dr-rabbitmq.example.com:5672/%2f"
  management_url: "http://dr-rabbitmq.example.com:15672"
  management_username: admin
  management_password: password

storage:
  backend: memory

caution

Importing definitions does not delete existing objects on the target. It adds or updates (merge behavior). Existing queues with different properties may cause errors.

Definitions in Full Backups

When include_definitions: true (the default), definitions are automatically exported as part of every backup:

backup:
  include_definitions: true  # default

The definitions are stored in the backup at {prefix}/{backup_id}/definitions/definitions.json.zst (compressed).

During restore, definitions are imported before messages when restore_definitions: true:

restore:
  restore_definitions: true  # default

Skip Definitions During Restore

If you only want to restore messages (for example, the topology already exists):

restore:
  restore_definitions: false

Selective Restore from Full Backups

For full backup restores, use restore.definitions_selection to import only the topology needed for a tenant, application, queue, or exchange.

restore-selected-definitions.yaml

mode: restore
backup_id: "prod-backup-2026-04-13"

target:
  amqp_url: "amqp://admin:${RMQ_PASSWORD}@dr-rabbitmq.example.com:5672/%2f"
  management_url: "http://dr-rabbitmq.example.com:15672"
  management_username: admin
  management_password: ${RMQ_MGMT_PASSWORD}

storage:
  backend: s3
  bucket: rabbitmq-backups
  region: us-east-1
  prefix: prod-cluster/

restore:
  restore_definitions: true
  definitions_dry_run: false
  definitions_selection:
    queues:
      - "orders"
    exchanges:
      - "orders-exchange"

Selection behavior:

Selector	Behavior
vhosts only	Restores all queues, exchanges, bindings, permissions, policies, and parameters scoped to those vhosts.
queues	Restores selected queues and the source exchanges/bindings required to route into them.
exchanges	Restores selected exchanges and bindings where both endpoints are retained.
empty selection	Restores all backed-up definitions.

Invalid selectors fail before import. For example, selecting a queue name that does not exist in the backup definitions returns an error and leaves the target unchanged.

tip

Use definitions_dry_run: true first to validate the selected definitions without importing them.

Rollback Snapshot and Compatibility Checks

During full restore with restore_definitions: true, rabbitmq-backup performs these safety checks before importing topology:

1. Downloads and decompresses the stored definitions JSON.
2. Validates the definitions JSON shape and required keys.
3. Applies definitions_selection if configured.
4. Fetches current target definitions and stores a rollback snapshot under {backup_id}/definitions/rollback-before-import-<timestamp>.<ext>.
5. Checks RabbitMQ major-version compatibility between the backup definitions and the target cluster.
6. Imports definitions through the Management API.

If any step fails, message restore does not proceed.

Standalone Selective Import

Import to a DR Cluster

Export from production and import to a disaster recovery cluster:

# Export from production
rabbitmq-backup definitions-export \
  --config prod-config.yaml \
  --output prod-definitions.json

# Import to DR
rabbitmq-backup definitions-import \
  --config dr-config.yaml \
  --input prod-definitions.json

Modify Before Import

You can edit the JSON file before importing to adjust for the target environment:

# Export
rabbitmq-backup definitions-export --config config.yaml --output defs.json

# Edit: change vhost, remove users, adjust policies
# (Use jq or any JSON editor)

# Remove a specific user
jq 'del(.users[] | select(.name == "temp-user"))' defs.json > defs-modified.json

# Import modified definitions
rabbitmq-backup definitions-import --config target-config.yaml --input defs-modified.json

Filter by Vhost Manually

Export definitions, then use jq to filter to a specific vhost before importing:

# Filter queues and bindings to vhost "production"
jq '{
  rabbit_version,
  rabbitmq_version,
  vhosts: [.vhosts[] | select(.name == "production")],
  users: .users,
  permissions: [.permissions[] | select(.vhost == "production")],
  exchanges: [.exchanges[] | select(.vhost == "production")],
  queues: [.queues[] | select(.vhost == "production")],
  bindings: [.bindings[] | select(.vhost == "production")],
  policies: [.policies[] | select(.vhost == "production")]
}' definitions.json > production-only.json

rabbitmq-backup definitions-import --config target-config.yaml --input production-only.json

Dry Run for Definitions

Use definitions_dry_run during a full restore to see what definitions would be imported without applying changes:

restore:
  restore_definitions: true
  definitions_dry_run: true

rabbitmq-backup restore -v --config restore.yaml

The output lists all definitions that would be created or updated without actually calling the Management API.

Automation: Periodic Definitions Backup

Even if you do not back up messages, schedule regular definitions exports as a lightweight safety net:

# Cron: export definitions daily at midnight
0 0 * * * rabbitmq-backup definitions-export \
  --config /etc/rabbitmq-backup/config.yaml \
  --output /var/lib/rabbitmq-backup/definitions/definitions-$(date +\%Y\%m\%d).json

Comparison with Built-in Tools

Feature	rabbitmqctl export_definitions	rabbitmq-backup definitions-export
Requires CLI on broker host	Yes	No (remote via Management API)
Works across network	No	Yes
Compressed storage	No	Yes (when part of full backup)
Integrates with message backup	No	Yes
Full-restore selective topology import	No	Yes (restore.definitions_selection)
Rollback snapshot before full restore import	No	Yes