1FEDORA-MESSAGING(1) Fedora Messaging FEDORA-MESSAGING(1)
2
3
4
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
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
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
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
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
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
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
159 Fedora Infrastructure
160
162 2018, Red Hat, Inc
163
164
165
166
1671.7 May 21, 2019 FEDORA-MESSAGING(1)