1FEDORA-MESSAGING(1)            Fedora Messaging            FEDORA-MESSAGING(1)
2
3
4

NAME

6       fedora-messaging - Fedora Messaging CLI
7

SYNOPSIS

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

DESCRIPTION

12       fedora-messaging  can  be  used to work with AMQP message brokers using
13       the fedora-messaging library to start message consumers.
14

OPTIONS

16       --help
17          Show help text and exit.
18
19       --conf
20          Path to a valid configuration file to use in place of the configura‐
21          tion in /etc/fedora-messaging/config.toml.
22

COMMANDS

24       There are three sub-commands, consume, publish and record, described in
25       detail in their own sections below.
26
27       fedora-messaging consume [OPTIONS]
28          Starts a consumer process with a user-provided callback function  to
29          execute when a message arrives.
30
31       fedora-messaging publish [OPTIONS] FILE
32          Loads  serialized  messages  from  a  file and publishes them to the
33          specified exchange.
34
35       fedora-messaging record [OPTIONS] FILE
36          Records messages arrived from AMQP queue and saves them to file with
37          specified name.
38
39   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
46       --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
52          This option is equivalent to the app setting in  the  client_proper‐
53          ties section of the configuration file.
54
55       --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
62          This  option is equivalent to the callback setting in the configura‐
63          tion file.
64
65       --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
71          Setting  this  option is equivalent to setting the routing_keys set‐
72          ting in all bindings entries in the configuration file.
73
74       --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
79          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
83       --exchange
84          The name of the exchange to bind the queue  to.  Can  contain  ASCII
85          letters, digits, hyphen, underscore, period, or colon.
86
87          Setting this option is equivalent to setting the exchange setting in
88          all bindings entries in the configuration file.
89
90   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
95          {
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
116       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
120          $ fedora-messaging publish -
121
122   Options
123       --exchange
124          The name of the exchange to publish to. Can contain  ASCII  letters,
125          digits, hyphen, underscore, period, or colon.
126
127   record
128       --limit
129          The maximum number of messages to record.
130
131       --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
137          This option is equivalent to the app setting in  the  client_proper‐
138          ties section of the configuration file.
139
140       --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
146          Setting this option is equivalent to setting the  routing_keys  set‐
147          ting in all bindings entries in the configuration file.
148
149       --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
154          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
158       --exchange
159          The  name  of  the  exchange to bind the queue to. Can contain ASCII
160          letters, digits, hyphen, underscore, period, or colon.
161
162          Setting this option is equivalent to setting the exchange setting in
163          all bindings entries in the configuration file.
164

EXIT CODES

166   consume
167       The consume command can exit for a number of reasons:
168
169       0
170          The  consumer  intentionally halted by raising a HaltConsumer excep‐
171          tion.
172
173       2
174          The argument or option provided is invalid.
175
176       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
183       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
188       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
194       13
195          An unexpected general exception is raised by your consumer callback.
196
197       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
201   publish
202       0
203          The messages were all successfully published.
204
205       1
206          A  general,  unexpected  exception  occurred and the message was not
207          successfully published.
208
209       121
210          The message broker rejected the message, likely due to resource con‐
211          straints.
212
213       111
214          A connection to the broker could not be established.
215

SIGNALS

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

SYSTEMD SERVICE

226       The consume subcommand can be started as a system service,  and  Fedora
227       Messaging provides a dynamic systemd service file.
228
229       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
234       Enable and start the service in systemd with the following commands:
235
236          systemctl enable fm-consumer@foo.service
237          systemctl start fm-consumer@foo.service
238
239       The service name after the @ and before the .service  must  match  your
240       filename in /etc/fedora-messaging (without the .toml suffix).
241

HELP

243       If you find bugs in fedora-messaging or its man page, please file a bug
244       report or a pull request:
245
246          https://github.com/fedora-infra/fedora-messaging
247
248       Or, if you prefer, send an  email  to  infrastructure@fedoraproject.org
249       with bug reports or patches.
250
251       fedora-messaging's documentation is available online:
252
253          https://fedora-messaging.readthedocs.io/
254

AUTHOR

256       Fedora Infrastructure
257
259       2023, Red Hat, Inc
260
261
262
263
2643.4                              Jul 19, 2023              FEDORA-MESSAGING(1)
Impressum