FEDORA-MESSAGING(1)

📦
version 3.9.1 · 4 versions
, in fedora 43

💖 FEDORA-MESSAGING(1) 💖

okay bestie, welcome to the fedora-messaging manual page, aka the Fedora Messaging CLI. buckle up, it's giving ✨infrastructure✨ and honestly? we ate.

🌸 NAME 🌸

fedora-messaging — the Fedora Messaging CLI, bestie. that's the whole name. short, sweet, iconic.

🦋 SYNOPSIS 🦋

fedora-messaging COMMAND [OPTIONS] [ARGS]...

like, you give it a command, you give it some options, you maybe give it some args, and it does the thing. periodt.

✨ DESCRIPTION ✨

so fedora-messaging is the tool you use to hang out with AMQP message brokers — it uses the fedora-messaging library to start up message consumers. that's the vibe. brokers, messages, consumers, all of it. 💅

🎀 OPTIONS 🎀

  • --help — shows you the help text and then dips. bye! 👋
  • --conf — the path to a valid config file to use instead of the config that lives at /etc/fedora-messaging/config.toml. so like, "not that config, this config." 💁

👑 COMMANDS 👑

there are three sub-commands, and they're all described in excruciating (affectionate) detail in their own sections below:

  • fedora-messaging consume [OPTIONS] — starts a consumer process with a callback function you provide, and it runs that callback whenever a message shows up. main character energy, honestly.
  • fedora-messaging publish [OPTIONS] FILE — loads serialized messages out of a file and publishes them to the exchange you specified. slay.
  • fedora-messaging record [OPTIONS] FILE — records messages that arrive from an AMQP queue and saves them to a file with the name you specified. it's giving "note-taking but for brokers." 📝

🍓 consume

okay so heads up: all the options below correspond to settings in the configuration file. BUT — and this is the important part, bestie — not every available configuration key can be overridden with options. so for complex setups and production environments, the recommendation is: use the config file and no options on the command line. iykyk.

  • --app-name — the name of the application. the AMQP client uses it to identify itself to the broker. it's purely for administrator convenience, so admins can tell which applications are connected and which ones own particular resources.

this option is equivalent to the app setting in the client_properties section of the configuration file.

  • --callback — the Python path to the callable object to execute when a message arrives. the Python path should be in the format module.path:object_in_module, and it should point to either a function or a class. go consult the API documentation for the interface these objects need to have. 📚

this option is equivalent to the callback setting in the configuration file.

  • --routing-key — the AMQP routing key to use with the queue. this controls what messages get delivered to the consumer. you can specify it multiple times, and any message that matches at least one of them gets placed in the message queue. very "collect them all." 🧚

setting this option is equivalent to setting the routing_keys setting in all bindings entries in the configuration file.

  • --queue-name — the name of the message queue in AMQP. it can contain ASCII letters, digits, hyphen, underscore, period, or colon. if you don't specify one, a unique name will be created for you. cute, right? 🎀

setting this option is equivalent to setting the queue setting in all bindings entries and creating a queue.<queue-name> section in the configuration file.

  • --exchange — the name of the exchange to bind the queue to. it can contain ASCII letters, digits, hyphen, underscore, period, or colon.

setting this option is equivalent to setting the exchange setting in all bindings entries in the configuration file.

🌈 publish

the publish command expects the message (or messages!) in FILE to be JSON objects, with each message separated by a newline character. the JSON object is described by this JSON schema, and yes you need all of it:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Schema for the JSON object used to represent messages in a file",
  "type": "object",
  "properties": {
      "topic": {"type": "string", "description": "The message topic"},
      "headers": {
          "type": "object",
          "properties": Message.headers_schema["properties"],
          "description": "The message headers",
      },
      "id": {"type": "string", "description": "The message's UUID."},
      "body": {"type": "object", "description": "The message body."},
      "queue": {
          "type": "string",
          "description": "The queue the message arrived on, if any.",
      },
  },
  "required": ["topic", "headers", "id", "body", "queue"],
}

these can be produced from Message objects by the fedora_messaging.api.dumps() API. and guess what — you can use stdin instead of a file by providing - as an argument. iconic:

$ fedora-messaging publish -

⭐ Options ⭐

  • --exchange — the name of the exchange to publish to. it can contain ASCII letters, digits, hyphen, underscore, period, or colon.

💜 record

  • --limit — the maximum number of messages to record. that's it, that's the whole thing. no cap.
  • --app-name — the name of the application. the AMQP client uses it to identify itself to the broker, and it's purely for administrator convenience so admins can figure out which applications are connected and own particular resources. if you don't specify it, the default is recorder.

this option is equivalent to the app setting in the client_properties section of the configuration file.

  • --routing-key — the AMQP routing key to use with the queue. this controls what messages get delivered to the consumer. it can be specified multiple times, and any message that matches at least one of them gets placed in the message queue.

setting this option is equivalent to setting the routing_keys setting in all bindings entries in the configuration file.

  • --queue-name — the name of the message queue in AMQP. it can contain ASCII letters, digits, hyphen, underscore, period, or colon. if one isn't specified, a unique name will be created for you. ✨

setting this option is equivalent to setting the queue setting in all bindings entries and creating a queue.<queue-name> section in the configuration file.

  • --exchange — the name of the exchange to bind the queue to. it can contain ASCII letters, digits, hyphen, underscore, period, or colon.

setting this option is equivalent to setting the exchange setting in all bindings entries in the configuration file.

💀 EXIT CODES 💀

🫶 consume

the consume command can exit for a whole bunch of reasons, and here's every single one of them:

  • 0 — the consumer intentionally halted by raising a HaltConsumer exception. graceful. respectful. we love to see it.
  • 2 — the argument or option you provided is invalid. bestie. 😭
  • 10 — the consumer was unable to declare an exchange, queue, or binding in the message broker. this happens when the user doesn't have permission on the broker to create the object, or the object already exists but doesn't have the attributes the consumer expects — like, say, the consumer expects it to be a durable queue but it's actually transient. rude.
  • 11 — the consumer hit an unexpected error while registering the consumer with the broker. this is a bug in fedora-messaging and should be reported. not us being messy, i promise. 🙈
  • 12 — the consumer was canceled by the message broker. this typically happens when the queue it's subscribed to gets deleted on the broker, but other exceptional cases could cause it too. in this case, the broker administrators should be consulted.
  • 13 — an unexpected general exception was raised by your consumer callback. (your callback. not ours. just saying. 💅)
also: consumer callbacks can cause the command to exit with a custom exit code. go consult the consumer's own documentation to see what error codes it uses.

🧚 publish

  • 0 — the messages were all successfully published. slay!
  • 1 — a general, unexpected exception occurred and the message was not successfully published.
  • 121 — the message broker rejected the message, likely due to resource constraints.
  • 111 — a connection to the broker could not be established.

🔥 SIGNALS 🔥

🌸 consume

the consume command handles the SIGTERM and SIGINT signals by letting any consumers that are currently processing a message finish up, acknowledging the message to the message broker, and then shutting down. so polite. so well-mannered.

repeated SIGTERM or SIGINT signals are ignored. so if you want it to halt immediately, you have to send SIGKILL — but be warned: messages that are only partially processed will be re-delivered when the consumer restarts. no take-backs. 💀

🌟 SYSTEMD SERVICE 🌟

the consume subcommand can be started as a system service, and Fedora Messaging ships a dynamic systemd service file for exactly this. 🎀

first, create a valid Fedora Messaging configuration file at /etc/fedora-messaging/foo.toml, with the callback parameter pointing to your consuming function or class. and remember — you can use the consumer_config section for your own configuration. it's your section, decorate it how you like. 💅

then enable and start the service in systemd with these commands:

systemctl enable fm-consumer@foo.service
systemctl start fm-consumer@foo.service
heads up: the service name after the @ and before the .service has to match your filename in /etc/fedora-messaging — without the .toml suffix. don't mess this up bestie, it will not work. 🙈

💖 HELP 💖

if you find bugs in fedora-messaging or in its man page, please file a bug report or a pull request:

https://github.com/fedora-infra/fedora-messaging

or, if you prefer, send an email to infrastructure@fedoraproject.org with bug reports or patches. either way, we're listening. 🫶

and fedora-messaging's documentation is available online:

https://fedora-messaging.readthedocs.io/

⭐ AUTHOR ⭐

Fedora Infrastructure

2018, Red Hat, Inc

okay that's the whole page, bestie, you made it to the end 💖 this was Fedora Messaging, version 3.9, dated Jun 23, 2026 — and that's on FEDORA-MESSAGING(1), periodt. now go start a consumer and be iconic. 👑✨

📦 where this page comes from