A shovel is used to move a message from a queue or exchange to a different queue or exchange. The queues or exchanges can reside on the same RabbitMQ node or on different RabbitMQ nodes.

AVOID TROUBLE

Before you can create a shovel, the rabbitmq_shovel plugin will need to be enabled, and you may want to also enable the rabbitmq_shovel_management plugin so that you can use Shovel Status and Shovel Management in the RabbitMQ web browser console and the RabbitMQ REST API to list/create/delete dynamic shovels. The rabbitmq-plugins list command can be used to determine if the plugins are enabled. If not, the rabbitmq-plugins enable command can be used to enable the plugins.

If the RabbitMQ node is not using SSL, the src-uri or dest-uri should start with amqp://. If SSL is being used, the src-uri or dest-uri should start with amqps://.

There are two types of shovels.

• Dynamic - Created using the rabbitmqctl set_parameter command (this article), or using the RabbitMQ REST API, or using the RabbitMQ web browser console, or using Terraform
• Static - defined in advanced.config, node must be restarted to create/delete a static shovel

The rabbitmqctl command with the set_parameter option can be used to create a dynamic shovel.

In this example, a shovel named shovel001 will be created that will move messages from a.queue to b.queue, where both queues must be running on the same RabbitMQ server. Notice that the source and destination URI is amqp://. With this URL, the shovel will be applied to the default / (forward slash) virtual host.

rabbitmqctl set_parameter shovel shovel001 
'{
  "src-uri": "amqp://",
  "src-queue": "a.queue",
  "dest-uri": "amqps://",
  "dest-queue": "b.queue"
}'

Notice in this example that --vhost foo and ampq:///foo are used. This will move messages from a.queue to b.queue in the foo virtual host, where both queues must be running on the same RabbitMQ server.

rabbitmqctl set_parameter shovel shovel001 
'{
  "src-uri": "amqp:///foo",
  "src-queue": "a.queue",
  "dest-uri": "amqps:///foo",
  "dest-queue": "b.queue"
}'
--vhost foo

Notice in this example that the source and destination URI contain a username and password, and different hostnames. This will move messages from a.queue on rabbit001.example.com to b.queue on rabbit002.example.com in the bar virtual host.

rabbitmqctl set_parameter shovel shovel001 
'{
  "src-uri": "amqp://john.doe:itsasecret@rabbit001.example.com:5672/bar",
  "src-queue": "a.queue",
  "dest-uri": "amqps://john.doe:itsasecret@rabbit002.example.com:5672/bar",
  "dest-queue": "b.queue"
}'
--vhost bar

Or in this example, src-exchange is used instead of src-queue.

rabbitmqctl set_parameter shovel shovel001 
'{
  "src-uri": "amqp://john.doe:itsasecret@rabbit001.example.com:5672/%2F",
  "src-exchange": "exchange001",
  "dest-uri": "amqps://john.doe:itsasecret@rabbit002.example.com:5672/%2F",
  "dest-queue": "queue002"
}'

Optionally, the AMQ protocol can be defined.

rabbitmqctl set_parameter shovel shovel001 
'{
  "src-protocol": "amqp091",
  "src-uri": "amqp://john.doe:itsasecret@rabbit001.example.com:5672/%2F",
  "src-exchange": "exchange001",
  "dest-protocol": "amqp091",
  "dest-uri": "amqps://john.doe:itsasecret@rabbit002.example.com:5672/%2F",
  "dest-queue": "queue002"
}'

Something like this should be returned.

Setting runtime parameter "shovel001" for component "shovel" to "{ "src-protocol": "amqp091", "src-uri": "amqp://rabbit001:5672/%2F", "src-queue": "queue001", "dest-protocol": "amqp091", "dest-uri": "amqp://rabbit002.example.com:5672/%2F", "dest-queue": "queue002" }" in vhost "/" ...

Likewise, if the shovel is successfully created, the following should be found in the main RabbitMQ log.

2021-06-03 03:35:24.406 [info] <0.28081.2> accepting AMQP connection <0.28081.2> (10.14.115.17:52841 -> 10.17.112.11:5671)

2021-06-03 03:35:24.407 [info] <0.28081.2> Connection <0.28081.2> (10.14.115.17:52841 -> 10.17.112.11:5671) has a client-provided name: Shovel shovel001

2021-06-03 03:35:24.408 [info] <0.28081.2> connection <0.28081.2> (10.14.115.17:52841 -> 10.17.112.11:5671 - Shovel shovel001): user 'john.doe' authenticated and granted access to vhost '/'

If the shovel source is an exchange, an exclusive queue will be created and the source exchange should be bound to the exclusive queue. An exclusive queue is a sort of temporary queue that will be removed after the shovel is terminated. The exclusive queue will begin with "amq.gen". The rabbitmqctl list_queues command can be used to list the exclusive queues. In this example, there is an exclusive queue in the foo virtual host.

~]$ rabbitmqctl list_queues name exclusive --vhost foo --formatter json | python -m json.tool
[
    {
        "exclusive": true,
        "name": "amq.gen-LuQ1NuuAT1gQ2R-gyeaOIw"
    }
]

Likewise, the rabbitmqctl list_bindings command should show that the source exchange is bound to the exclusive queue.

~]# rabbitmqctl list_bindings --vhost foo --formatter json | python -m json.tool
[
    {
        "arguments": [],
        "destination_kind": "queue",
        "destination_name": "amq.gen-LuQ1NuuAT1gQ2R-gyeaOIw",
        "routing_key": "key002",
        "source_kind": "exchange",
        "source_name": "exchange001"
    }
]