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  is  a single sub-command, consume, described in detail in its ow
25       section 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   consume
32       All  options  below  correspond  to settings in the configuration file.
33       However, not all available configuration keys can  be  overridden  with
34       options,  so  it  is recommended that for complex setups and production
35       environments you use the configuration file and no options on the  com‐
36       mand line.
37
38       --app-name
39          The  name  of  the  application, used by the AMQP client to identify
40          itself to the broker. This is purely for  administrator  convenience
41          to  determine  what  applications  are  connected and own particular
42          resources.
43
44          This option is equivalent to the app setting in  the  client_proper‐
45          ties section of the configuration file.
46
47       --callback
48          The  Python  path  to  the callable object to execute when a message
49          arrives.   The  Python  path  should   be   in   the   format   mod‐
50          ule.path:object_in_module and should point to either a function or a
51          class. Consult the API documentation for the interface required  for
52          these objects.
53
54          This  option is equivalent to the callback setting in the configura‐
55          tion file.
56
57       --routing-key
58          The AMQP routing key to use with the queue. This controls what  mes‐
59          sages  are  delivered  to  the  consumer.  Can be specified multiple
60          times; any message that matches at least one will be placed  in  the
61          message queue.
62
63          Setting  this  option is equivalent to setting the routing_keys set‐
64          ting in all bindings entries in the configuration file.
65
66       --queue-name
67          The name of the message queue in AMQP. Can  contain  ASCII  letters,
68          digits,  hyphen,  underscore, period, or colon. If one is not speci‐
69          fied, a unique name will be created for you.
70
71          Setting this option is equivalent to setting the  queue  setting  in
72          all  bindings  entries  and creating a queue.<queue-name> section in
73          the configuration file.
74
75       --exchange
76          The name of the exchange to bind the queue  to.  Can  contain  ASCII
77          letters, digits, hyphen, underscore, period, or colon. If one is not
78          specified, the default is the amq.topic exchange.
79
80          Setting this option is equivalent to setting the exchange setting in
81          all bindings entries in the configuration file.
82

EXIT CODES

84   consume
85       The consume command can exit for a number of reasons:
86
87       0
88          The  consumer  intentionally halted by raising a HaltConsumer excep‐
89          tion.
90
91       2
92          The argument or option provided is invalid.
93
94       10
95          The consumer was unable to declare an exchange, queue, or binding in
96          the  message broker. This occurs with the user does not have permis‐
97          sion on the broker to  create  the  object  or  the  object  already
98          exists,  but does not have the attributes the consumer expects (e.g.
99          the consumer expects it to be a durable queue, but it is transient).
100
101       11
102          The consumer encounters an unexpected error  while  registering  the
103          consumer  with  the  broker.  This  is a bug in fedora-messaging and
104          should be reported.
105
106       12
107          The consumer is canceled by the message  broker.   The  consumer  is
108          typically  canceled when the queue it is subscribed to is deleted on
109          the broker, but other exceptional cases could result  in  this.  The
110          broker administrators should be consulted in this case.
111
112       13
113          An unexpected general exception is raised by your consumer callback.
114
115       Additionally,  consumer  callbacks can cause the command to exit with a
116       custom exit code. Consult the  consumer's  documentation  to  see  what
117       error codes it uses.
118

SIGNALS

120   consume
121       The  consume command handles the SIGTERM and SIGINT signals by allowing
122       any consumers which are  currently  processing  a  message  to  finish,
123       acknowledging  the  message  to  the  message broker, and then shutting
124       down. Repeated SIGTERM or SIGINT signals are ignored. To  halt  immedi‐
125       ately,  send  the SIGKILL signal; messages that are partially processed
126       will be re-delivered when the consumer restarts.
127

SYSTEMD SERVICE

129       The consume subcommand can be started as a system service,  and  Fedora
130       Messaging provides a dynamic systemd service file.
131
132       First,   create   a   valid  Fedora  Messaging  configuration  file  in
133       /etc/fedora-messaging/foo.toml, with the callback parameter pointing to
134       your  consuming  function  or class. Remember that you can use the con‐
135       sumer_config section for your own configuration.
136
137       Enable and start the service in systemd with the following commands:
138
139          systemctl enable fm-consumer@foo.service
140          systemctl start fm-consumer@foo.service
141
142       The service name after the @ and before the .service  must  match  your
143       filename in /etc/fedora-messaging (without the .toml suffix).
144

HELP

146       If you find bugs in fedora-messaging or its man page, please file a bug
147       report or a pull request:
148
149          https://github.com/fedora-infra/fedora-messaging
150
151       Or, if you prefer, send an  email  to  infrastructure@fedoraproject.org
152       with bug reports or patches.
153
154       fedora-messaging's documentation is available online:
155
156          https://fedora-messaging.readthedocs.io/
157

AUTHOR

159       Fedora Infrastructure
160
162       2018, Red Hat, Inc
163
164
165
166
1671.7                              May 21, 2019              FEDORA-MESSAGING(1)
Impressum