1STOMPCLT(1) User Contributed Perl Documentation STOMPCLT(1)
2
6 stompclt - versatile STOMP client
7
9 stompclt [OPTIONS]
10
12 stompclt is a versatile tool to interact with messaging brokers
13 speaking STOMP and/or message queues (see Messaging::Message::Queue) on
14 disk.
15 It receives messages (see Messaging::Message) from an incoming module,
17 optionally massaging them (i.e. filtering and/or modifying), and sends
18 them to an outgoing module. Depending on which modules are used, the
19 tool can perform different operations.
20 Here are the supported incoming modules:
22 • broker: connect to a messaging broker using STOMP, subscribe to one
24 or more destinations and receive the messages sent by the broker
25 • queue: read messages from a message queue on disk
27 Here are the supported outgoing modules:
29 • broker: connect to a messaging broker using STOMP and send the
31 messages
32 • queue: store the messages in a message queue on disk
34 Here are some frequently used combinations:
36 • incoming broker + outgoing queue: drain some destinations, storing
38 the messages on disk
39 • incoming queue + outgoing broker: (re-)send messages that have been
41 previously stored on disk, optionally with modifications (such as
42 altering the destination)
43 • incoming broker + outgoing broker: shovel messages from one broker
45 to another
46 See the "EXAMPLES" sections for concrete examples.
48
50 --callback-code CODE
51 execute the given Perl code on each message, see the "CALLBACK"
52 section below for more information
53 --callback-data KEY=VALUE...
55 pass this data to the user supplied callback code, see the
56 "CALLBACK" section below for more information
57 --callback-path PATH
59 execute the Perl code in the given file on each message, see the
60 "CALLBACK" section below for more information
61 --config, --conf, --cfg PATH
63 use the given configuration file, see the "CONFIGURATION FILE"
64 section below for more information
65 --config-general KEY=VALUE...
67 use the given Config::General options when creating the
68 configuration parser
69 --count, -c INTEGER
71 process at most the given number of messages; note: when using an
72 incoming broker, to avoid consuming more messages, it is
73 recommended to enable the --reliable option
74 --daemon | --no-daemon
76 detach stompclt so that it becomes a daemon running in the
77 background; debug, warning and error messages will get sent to
78 syslog; this option can be negated
79 --debug, -d
81 show debugging information
82 --duration SECONDS
84 process messages during at most the given number of seconds and
85 then stop; can be fractional
86 --heart-beat | --no-heart-beat
88 enable STOMP 1.1 heart-beats between stompclt and the broker(s);
89 this option can be negated
90 --help, -h, -?
92 show some help
93 --incoming-broker-auth STRING
95 use this authentication string (see Authen::Credential) to
96 authenticate to the incoming broker; this option can be given
97 multiple times
98 --incoming-broker-connect KEY=VALUE...
100 use these options in the STOMP CONNECT frame sent to the incoming
101 broker
102 --incoming-broker-sockopts KEY=VALUE...
104 use these socket options when connecting to the incoming broker
105 --incoming-broker-stomp-debug STRING
107 set the STOMP debug flags (see Net::STOMP::Client) when interacting
108 with the incoming broker
109 --incoming-broker-type STRING
111 set the incoming broker type; this can be useful when using STOMP
112 features which are broker specific
113 --incoming-broker-uri URI
115 use this connection URI (see Net::STOMP::Client) to connect to the
116 incoming broker
117 --incoming-queue KEY=VALUE...
119 read incoming messages from the given message queue (see
120 Messaging::Message::Queue)
121 --lazy | --no-lazy
123 initialize the outgoing module only after having received the first
124 message; this option can be negated
125 --list, -l
127 show all supported options
128 --loop | --no-loop
130 when using an incoming message queue, loop over it; this option can
131 be negated
132 --manual, -m
134 show this manual
135 --outgoing-broker-auth STRING
137 use this authentication string (see Authen::Credential) to
138 authenticate to the outgoing broker; this option can be given
139 multiple times
140 --outgoing-broker-connect KEY=VALUE...
142 use these options in the STOMP CONNECT frame sent to the outgoing
143 broker
144 --outgoing-broker-sockopts KEY=VALUE...
146 use these socket options when connecting to the outgoing broker
147 --outgoing-broker-stomp-debug STRING
149 set the STOMP debug flags (see Net::STOMP::Client) when interacting
150 with the outgoing broker
151 --outgoing-broker-type STRING
153 set the outgoing broker type; this can be useful when using STOMP
154 features which are broker specific
155 --outgoing-broker-uri URI
157 use this connection URI (see Net::STOMP::Client) to connect to the
158 outgoing broker
159 --outgoing-queue KEY=VALUE...
161 store outgoing messages into the given message queue (see
162 Messaging::Message::Queue)
163 --pidfile PATH
165 use this pid file
166 --prefetch INTEGER
168 set the prefetch value (i.e. the maximum number of messages to
169 received without acknowledging them) on the incoming broker
170 --quit
172 tell another instance of stompclt (identified by its pid file, as
173 specified by the --pidfile option) to quit
174 --reliable | --no-reliable
176 use STOMP features for more reliable messaging (i.e. client side
177 acknowledgments and receipts) at the cost of less performance; this
178 option can be negated
179 --remove | --no-remove
181 when using an incoming message queue, remove the processed
182 messages; this option can be negated
183 --statistics, -s | --no-statistics
185 report statistics at the end of the execution; this option can be
186 negated
187 --status
189 get the status of another instance of stompclt (identified by its
190 pid file, as specified by the --pidfile option); the exit code will
191 be zero if the instance is alive and non-zero otherwise
192 --subscribe KEY=VALUE...
194 use these options in the STOMP SUBSCRIBE frame used with the
195 incoming broker; this option can be given multiple times
196 --timeout-broker SECONDS
198 use this timeout when interacting with the broker (e.g. getting
199 receipts back); can be fractional
200 --timeout-client SECONDS
202 use this timeout for the client heart-beat; can be fractional
203 (default: 40)
204 --timeout-connect SECONDS
206 use this timeout when connecting to the broker; can be fractional
207 --timeout-disconnect SECONDS
209 use this timeout when disconnecting from the broker; can be
210 fractional (default: 60)
211 --timeout-flush SECONDS
213 use this timeout when attempting to send the last bytes to the
214 broker just before disconnecting; can be fractional (default: 60)
215 --timeout-inactivity SECONDS
217 use this timeout in the incoming module to stop stompclt when no
218 new messages have been received (aka drain mode); can be fractional
219 --timeout-linger SECONDS
221 when stopping stompclt, use this timeout to finish interacting with
222 the broker; can be fractional
223 --timeout-server SECONDS
225 use this timeout for the server heart-beat; can be fractional
226 (default: 10)
227 --timeout-status SECONDS
229 use this timeout when checking the status with --status; can be
230 fractional
231 --unsubscribe KEY=VALUE...
233 use these options in the STOMP UNSUBSCRIBE frame used with the
234 incoming broker; this option can be given multiple times and should
235 match the --subscribe options
236 --version
238 display version information
239 --window INTEGER
241 keep at most the given number of not-yet-acknowledged messages in
242 memory
243 To list all the available options in a compact form, type:
245 $ stompclt -l
247
249 stompclt can read its options from a configuration file. For this, the
250 Config::General module is used and the option names are the same as on
251 the command line. For instance:
252 daemon = true
254 pidfile = /var/run/stompclt.pid
255 incoming-queue = path=/var/spool/stompclt
256 outgoing-broker-uri = stomp://broker.acme.com:6163
257 outgoing-broker-auth = "plain name=guest pass=guest"
258 Alternatively, options can be nested:
260 <outgoing-broker>
262 uri = stomp://broker.acme.com:6163
263 auth = "plain name=guest pass=guest"
264 </outgoing-broker>
265 Or even:
267 <outgoing>
269 <broker>
270 uri = stomp://broker.acme.com:6163
271 <auth>
272 scheme = plain
273 name = guest
274 pass = guest
275 </auth>
276 </broker>
277 </outgoing>
278 The options specified on the command line have precedence over the ones
280 found in the configuration file.
281
283 stompclt can be given Perl code to execute on all processed messages.
284 This can be used for different purposes:
285 • massaging: the code can change any part of the message, including
287 setting or removing header fields
288 • filtering: the code can decide if the message must be given to the
290 outgoing module or not
291 • displaying: the code can print any part of the message
293 • copying: the code can store a copy of the message into files or
295 message queues
296 To use callbacks, the --callback-path or --callback-code option must be
298 used. The Perl code must provide functions with the following
299 signature:
300 start(DATA)
302 (optional) this will be called when the program starts, with the
303 supplied data (see the --callback-data option) as a hash reference
304 check(MESSAGE)
306 (mandatory) this will be called when the program has one message to
307 process; it will be given the message (see Messaging::Message) and
308 must return either a message (it could be the same one or a new
309 one) or a string describing why the message has been dropped
310 idle()
312 (optional) this will be called when the program has no message to
313 process
314 stop()
316 (optional) this will be called when the program stops
317 The code can be put in a file, on the command line or in the stompclt
319 configuration file, using the "here document" syntax.
320 Here is an example (to be put in the stompclt configuration file) that
322 prints on stdout a JSON array of messages:
323 callback-code = <<EOF
325 my($count);
326 sub start ($) {
327 $count = 0;
328 }
329 sub check ($) {
330 my($msg) = @_;
331 print($count++ ? "," : "[");
332 print($msg->serialize(), "\n");
333 return($msg);
334 }
335 sub stop () {
336 print($count ? "]\n" : "[]\n");
337 }
338 EOF
339 For simple callback code that only needs the "check" subroutine, it is
341 enough to supply the "inside code". If the subroutine definition is
342 missing, the supplied code will be wrapped with:
343 sub check ($) {
345 my($msg) = @_;
346 local *hdr = $msg->header();
347 local *bdy = $msg->body_ref();
348 ... your code goes here ...
349 return($msg);
350 }
351 This allows for instance to remove the "message-id" header with
353 something like:
354 $ stompclt ... --callback-code 'delete($hdr{"message-id"})'
356 Or to filter on message bodies with:
358 $ stompclt ... --callback-code 'return("skip") unless $bdy =~ /error/'
360
362 In the case of an incoming broker, stompclt deals with the
363 subscriptions defined by the --subscribe option.
364 Regardless of the --reliable option, subscriptions are always made
366 using receipts. Also, if missing, an "id" header is always added.
367 Here is for instance how to create a named durable topic subscription
369 using Apollo:
370 $ stompclt ... --subscribe 'destination=/topic/foo persistent=true id=mysub'
372 By default, when it finishes, stompclt does not unsubscribe. It simply
374 disconnects from the broker and the latter will perform the necessary
375 cleanup when terminating the STOMP connection.
376 If the --unsubscribe option is given, even if it is empty, stompclt
378 will explicitly unsubscribe before disconnecting, also using receipts.
379 Here is for instance how to destroy, when stompclt ends, the durable
381 topic subscription created above:
382 $ stompclt ... --unsubscribe 'persistent=true'
384 There is no need to give the subscription "id" in the --unsubscribe
386 option because, by default, it comes from the matching --subscribe
387 option.
388
390 stompclt has experimental UDP support (outgoing only). This has been
391 tested with Apollo.
392 To use it, simply specify an outgoing URI that uses UDP such as:
394 $ stompclt ... --outgoing-broker-uri udp://broker.acme.com:6163
396 Features such as authentication, heart beating, reliability and socket
398 options are not supported over UDP.
399
401 SENDING
402 Here is an example of a configuration file for a message sender daemon
403 (from queue to broker), forcing the "persistent" header to "true"
404 (something which is highly recommended for reliable messaging) and
405 setting the destination:
406 # define the source message queue
408 <incoming-queue>
409 path = /var/spool/sender
410 </incoming-queue>
411 # modify the message header on the fly
412 callback-code = <<EOF
413 $hdr{destination} = "/queue/app1.data";
414 $hdr{persistent} = "true";
415 EOF
416 # define the destination broker
417 <outgoing-broker>
418 uri = "stomp://broker.acme.com:6163"
419 </outgoing-broker>
420 # miscellaneous options
421 reliable = true
422 pidfile = /var/run/sender.pid
423 daemon = true
424 loop = true
425 remove = true
426 RECEIVING
428 Here is an example of a configuration file for a message receiver
429 daemon (from broker to queue):
430 # define the source broker
432 <incoming-broker>
433 uri = "stomp://broker.acme.com:6163"
434 <auth>
435 scheme = plain
436 name = receiver
437 pass = secret
438 </auth>
439 </incoming-broker>
440 # define the subscriptions
441 <subscribe>
442 destination = /queue/app1.data
443 </subscribe>
444 <subscribe>
445 destination = /queue/app2.data
446 </subscribe>
447 # define the destination message queue
448 <outgoing-queue>
449 path = /var/spool/receiver
450 </outgoing-queue>
451 # miscellaneous options
452 pidfile = /var/run/receiver.pid
453 daemon = true
454 Here is how to use the configuration file above with some options
456 overridden on the command line to drain the queues in the foreground:
457 $ stompclt --config test.conf --no-daemon --timeout-inactivity 10
459 SHOVELING
461 Here is an example of a configuration file for a message shoveler (from
462 broker to broker), clearing some headers on the fly so that messages
463 can be replayed safely:
464 # define the source broker
466 <incoming-broker>
467 uri = "stomp://broker.acme.com:6163"
468 </incoming-broker>
469 # define the subscriptions
470 <subscribe>
471 destination = /queue/app1.data
472 </subscribe>
473 <subscribe>
474 destination = /queue/app2.data
475 </subscribe>
476 # define the destination broker
477 <outgoing-broker>
478 uri = "stomp://dev-broker.acme.com:6163"
479 </outgoing-broker>
480 # modify the message so that it can be replayed
481 callback-code = <<EOF
482 foreach my $name (qw(message-id timestamp expires)) {
483 delete($hdr{$name});
484 }
485 EOF
486 TAPPING
488 Callback code can also be used to tap messages, i.e. get a copy of all
489 messages processed by stompclt. Here is some callback code for this
490 purpose that could for instance be merged with the shoveling code
491 above. It also shows how to use the --callback-data option:
492 callback-code = <<EOF
494 my($queue);
495 sub start ($) {
496 my($data) = @_;
497 $queue = Messaging::Message::Queue->new($data);
498 }
499 sub check ($) {
500 my($msg) = @_;
501 $queue->add_message($msg);
502 return($msg);
503 }
504 EOF
505 Callback data must be given to specify which message queue to use:
507 $ stompclt --config tap.conf --callback-data "path=/tmp/tap type=DQS"
509
511 Authen::Credential, Config::General, Messaging::Message,
512 Messaging::Message::Queue, Net::STOMP::Client.
513
515 Lionel Cons <http://cern.ch/lionel.cons>
516 Copyright (C) CERN 2012-2021
518perl v5.34.0 2022-01-22 STOMPCLT(1)