1FEDORA-MESSAGING(1) Fedora Messaging FEDORA-MESSAGING(1)
2
6 fedora-messaging - Fedora Messaging CLI
7
9 fedora-messaging COMMAND [OPTIONS] [ARGS]...
10
12 fedora-messaging can be used to work with AMQP message brokers using
13 the fedora-messaging library to start message consumers.
14
16 --help
17 Show help text and exit.
18 --conf
20 Path to a valid configuration file to use in place of the configura‐
21 tion in /etc/fedora-messaging/config.toml.
22
24 There are three sub-commands, consume, publish and record, described in
25 detail in their own sections below.
26 fedora-messaging consume [OPTIONS]
28 Starts a consumer process with a user-provided callback function to
29 execute when a message arrives.
30 fedora-messaging publish [OPTIONS] FILE
32 Loads serialized messages from a file and publishes them to the
33 specified exchange.
34 fedora-messaging record [OPTIONS] FILE
36 Records messages arrived from AMQP queue and saves them to file with
37 specified name.
38 consume
40 All options below correspond to settings in the configuration file.
41 However, not all available configuration keys can be overridden with
42 options, so it is recommended that for complex setups and production
43 environments you use the configuration file and no options on the com‐
44 mand line.
45 --app-name
47 The name of the application, used by the AMQP client to identify it‐
48 self to the broker. This is purely for administrator convenience to
49 determine what applications are connected and own particular re‐
50 sources.
51 This option is equivalent to the app setting in the client_proper‐
53 ties section of the configuration file.
54 --callback
56 The Python path to the callable object to execute when a message ar‐
57 rives. The Python path should be in the format module.path:ob‐
58 ject_in_module and should point to either a function or a class.
59 Consult the API documentation for the interface required for these
60 objects.
61 This option is equivalent to the callback setting in the configura‐
63 tion file.
64 --routing-key
66 The AMQP routing key to use with the queue. This controls what mes‐
67 sages are delivered to the consumer. Can be specified multiple
68 times; any message that matches at least one will be placed in the
69 message queue.
70 Setting this option is equivalent to setting the routing_keys set‐
72 ting in all bindings entries in the configuration file.
73 --queue-name
75 The name of the message queue in AMQP. Can contain ASCII letters,
76 digits, hyphen, underscore, period, or colon. If one is not speci‐
77 fied, a unique name will be created for you.
78 Setting this option is equivalent to setting the queue setting in
80 all bindings entries and creating a queue.<queue-name> section in
81 the configuration file.
82 --exchange
84 The name of the exchange to bind the queue to. Can contain ASCII
85 letters, digits, hyphen, underscore, period, or colon.
86 Setting this option is equivalent to setting the exchange setting in
88 all bindings entries in the configuration file.
89 publish
91 The publish command expects the message or messages provided in FILE to
92 be JSON objects with each message separated by a newline character. The
93 JSON object is described by the following JSON schema:
94 {
96 "$schema": "http://json-schema.org/draft-04/schema#",
97 "description": "Schema for the JSON object used to represent messages in a file",
98 "type": "object",
99 "properties": {
100 "topic": {"type": "string", "description": "The message topic"},
101 "headers": {
102 "type": "object",
103 "properties": Message.headers_schema["properties"],
104 "description": "The message headers",
105 },
106 "id": {"type": "string", "description": "The message's UUID."},
107 "body": {"type": "object", "description": "The message body."},
108 "queue": {
109 "type": "string",
110 "description": "The queue the message arrived on, if any.",
111 },
112 },
113 "required": ["topic", "headers", "id", "body", "queue"],
114 }
115 They can be produced from Message objects by the fedora_messag‐
117 ing.api.dumps() API. stdin can be used instead of a file by providing -
118 as an argument:
119 $ fedora-messaging publish -
121 Options
123 --exchange
124 The name of the exchange to publish to. Can contain ASCII letters,
125 digits, hyphen, underscore, period, or colon.
126 record
128 --limit
129 The maximum number of messages to record.
130 --app-name
132 The name of the application, used by the AMQP client to identify it‐
133 self to the broker. This is purely for administrator convenience to
134 determine what applications are connected and own particular re‐
135 sources. If not specified, the default is recorder.
136 This option is equivalent to the app setting in the client_proper‐
138 ties section of the configuration file.
139 --routing-key
141 The AMQP routing key to use with the queue. This controls what mes‐
142 sages are delivered to the consumer. Can be specified multiple
143 times; any message that matches at least one will be placed in the
144 message queue.
145 Setting this option is equivalent to setting the routing_keys set‐
147 ting in all bindings entries in the configuration file.
148 --queue-name
150 The name of the message queue in AMQP. Can contain ASCII letters,
151 digits, hyphen, underscore, period, or colon. If one is not speci‐
152 fied, a unique name will be created for you.
153 Setting this option is equivalent to setting the queue setting in
155 all bindings entries and creating a queue.<queue-name> section in
156 the configuration file.
157 --exchange
159 The name of the exchange to bind the queue to. Can contain ASCII
160 letters, digits, hyphen, underscore, period, or colon.
161 Setting this option is equivalent to setting the exchange setting in
163 all bindings entries in the configuration file.
164
166 consume
167 The consume command can exit for a number of reasons:
168 0
170 The consumer intentionally halted by raising a HaltConsumer excep‐
171 tion.
172 2
174 The argument or option provided is invalid.
175 10
177 The consumer was unable to declare an exchange, queue, or binding in
178 the message broker. This occurs with the user does not have permis‐
179 sion on the broker to create the object or the object already ex‐
180 ists, but does not have the attributes the consumer expects (e.g.
181 the consumer expects it to be a durable queue, but it is transient).
182 11
184 The consumer encounters an unexpected error while registering the
185 consumer with the broker. This is a bug in fedora-messaging and
186 should be reported.
187 12
189 The consumer is canceled by the message broker. The consumer is
190 typically canceled when the queue it is subscribed to is deleted on
191 the broker, but other exceptional cases could result in this. The
192 broker administrators should be consulted in this case.
193 13
195 An unexpected general exception is raised by your consumer callback.
196 Additionally, consumer callbacks can cause the command to exit with a
198 custom exit code. Consult the consumer's documentation to see what er‐
199 ror codes it uses.
200 publish
202 0
203 The messages were all successfully published.
204 1
206 A general, unexpected exception occurred and the message was not
207 successfully published.
208 121
210 The message broker rejected the message, likely due to resource con‐
211 straints.
212 111
214 A connection to the broker could not be established.
215
217 consume
218 The consume command handles the SIGTERM and SIGINT signals by allowing
219 any consumers which are currently processing a message to finish, ac‐
220 knowledging the message to the message broker, and then shutting down.
221 Repeated SIGTERM or SIGINT signals are ignored. To halt immediately,
222 send the SIGKILL signal; messages that are partially processed will be
223 re-delivered when the consumer restarts.
224
226 The consume subcommand can be started as a system service, and Fedora
227 Messaging provides a dynamic systemd service file.
228 First, create a valid Fedora Messaging configuration file in /etc/fe‐
230 dora-messaging/foo.toml, with the callback parameter pointing to your
231 consuming function or class. Remember that you can use the con‐
232 sumer_config section for your own configuration.
233 Enable and start the service in systemd with the following commands:
235 systemctl enable fm-consumer@foo.service
237 systemctl start fm-consumer@foo.service
238 The service name after the @ and before the .service must match your
240 filename in /etc/fedora-messaging (without the .toml suffix).
241
243 If you find bugs in fedora-messaging or its man page, please file a bug
244 report or a pull request:
245 https://github.com/fedora-infra/fedora-messaging
247 Or, if you prefer, send an email to infrastructure@fedoraproject.org
249 with bug reports or patches.
250 fedora-messaging's documentation is available online:
252 https://fedora-messaging.readthedocs.io/
254
256 Fedora Infrastructure
257
259 2023, Red Hat, Inc
2603.4 Jul 19, 2023 FEDORA-MESSAGING(1)