1STOMPCLT(1)           User Contributed Perl Documentation          STOMPCLT(1)
2
3
4

NAME

6       stompclt - versatile STOMP client
7

SYNOPSIS

9       stompclt [OPTIONS]
10

DESCRIPTION

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
16       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
21       Here are the supported incoming modules:
22
23       ·   broker: connect to a messaging broker using STOMP, subscribe to one
24           or more destinations and receive the messages sent by the broker
25
26       ·   queue: read messages from a message queue on disk
27
28       Here are the supported outgoing modules:
29
30       ·   broker: connect to a messaging broker using STOMP and send the
31           messages
32
33       ·   queue: store the messages in a message queue on disk
34
35       Here are some frequently used combinations:
36
37       ·   incoming broker + outgoing queue: drain some destinations, storing
38           the messages on disk
39
40       ·   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
44       ·   incoming broker + outgoing broker: shovel messages from one broker
45           to another
46
47       See the "EXAMPLES" sections for concrete examples.
48

OPTIONS

50       --callback-code CODE
51           execute the given Perl code on each message, see the "CALLBACK"
52           section below for more information
53
54       --callback-data KEY=VALUE...
55           pass this data to the user supplied callback code, see the
56           "CALLBACK" section below for more information
57
58       --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
62       --config, --conf, --cfg PATH
63           use the given configuration file, see the "CONFIGURATION FILE"
64           section below for more information
65
66       --config-general KEY=VALUE...
67           use the given Config::General options when creating the
68           configuration parser
69
70       --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
75       --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
80       --debug, -d
81           show debugging information
82
83       --duration SECONDS
84           process messages during at most the given number of seconds and
85           then stop; can be fractional
86
87       --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
91       --help, -h, -?
92           show some help
93
94       --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
99       --incoming-broker-connect KEY=VALUE...
100           use these options in the STOMP CONNECT frame sent to the incoming
101           broker
102
103       --incoming-broker-sockopts KEY=VALUE...
104           use these socket options when connecting to the incoming broker
105
106       --incoming-broker-stomp-debug STRING
107           set the STOMP debug flags (see Net::STOMP::Client) when interacting
108           with the incoming broker
109
110       --incoming-broker-type STRING
111           set the incoming broker type; this can be useful when using STOMP
112           features which are broker specific
113
114       --incoming-broker-uri URI
115           use this connection URI (see Net::STOMP::Client) to connect to the
116           incoming broker
117
118       --incoming-queue KEY=VALUE...
119           read incoming messages from the given message queue (see
120           Messaging::Message::Queue)
121
122       --lazy | --no-lazy
123           initialize the outgoing module only after having received the first
124           message; this option can be negated
125
126       --list, -l
127           show all supported options
128
129       --loop | --no-loop
130           when using an incoming message queue, loop over it; this option can
131           be negated
132
133       --manual, -m
134           show this manual
135
136       --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
141       --outgoing-broker-connect KEY=VALUE...
142           use these options in the STOMP CONNECT frame sent to the outgoing
143           broker
144
145       --outgoing-broker-sockopts KEY=VALUE...
146           use these socket options when connecting to the outgoing broker
147
148       --outgoing-broker-stomp-debug STRING
149           set the STOMP debug flags (see Net::STOMP::Client) when interacting
150           with the outgoing broker
151
152       --outgoing-broker-type STRING
153           set the outgoing broker type; this can be useful when using STOMP
154           features which are broker specific
155
156       --outgoing-broker-uri URI
157           use this connection URI (see Net::STOMP::Client) to connect to the
158           outgoing broker
159
160       --outgoing-queue KEY=VALUE...
161           store outgoing messages into the given message queue (see
162           Messaging::Message::Queue)
163
164       --pidfile PATH
165           use this pid file
166
167       --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
171       --quit
172           tell another instance of stompclt (identified by its pid file, as
173           specified by the --pidfile option) to quit
174
175       --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
180       --remove | --no-remove
181           when using an incoming message queue, remove the processed
182           messages; this option can be negated
183
184       --statistics, -s | --no-statistics
185           report statistics at the end of the execution; this option can be
186           negated
187
188       --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
193       --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
197       --timeout-broker SECONDS
198           use this timeout when interacting with the broker (e.g. getting
199           receipts back); can be fractional
200
201       --timeout-client SECONDS
202           use this timeout for the client heart-beat; can be fractional
203           (default: 40)
204
205       --timeout-connect SECONDS
206           use this timeout when connecting to the broker; can be fractional
207
208       --timeout-disconnect SECONDS
209           use this timeout when disconnecting from the broker; can be
210           fractional (default: 60)
211
212       --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
216       --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
220       --timeout-linger SECONDS
221           when stopping stompclt, use this timeout to finish interacting with
222           the broker; can be fractional
223
224       --timeout-server SECONDS
225           use this timeout for the server heart-beat; can be fractional
226           (default: 10)
227
228       --timeout-status SECONDS
229           use this timeout when checking the status with --status; can be
230           fractional
231
232       --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
237       --version
238           display version information
239
240       --window INTEGER
241           keep at most the given number of not-yet-acknowledged messages in
242           memory
243
244       To list all the available options in a compact form, type:
245
246         $ stompclt -l
247

CONFIGURATION FILE

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
253         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
259       Alternatively, options can be nested:
260
261         <outgoing-broker>
262             uri = stomp://broker.acme.com:6163
263             auth = "plain name=guest pass=guest"
264         </outgoing-broker>
265
266       Or even:
267
268         <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
279       The options specified on the command line have precedence over the ones
280       found in the configuration file.
281

CALLBACK

283       stompclt can be given Perl code to execute on all processed messages.
284       This can be used for different purposes:
285
286       ·   massaging: the code can change any part of the message, including
287           setting or removing header fields
288
289       ·   filtering: the code can decide if the message must be given to the
290           outgoing module or not
291
292       ·   displaying: the code can print any part of the message
293
294       ·   copying: the code can store a copy of the message into files or
295           message queues
296
297       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
301       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
305       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
311       idle()
312           (optional) this will be called when the program has no message to
313           process
314
315       stop()
316           (optional) this will be called when the program stops
317
318       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
321       Here is an example (to be put in the stompclt configuration file) that
322       prints on stdout a JSON array of messages:
323
324         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
340       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
344         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
352       This allows for instance to remove the "message-id" header with
353       something like:
354
355         $ stompclt ... --callback-code 'delete($hdr{"message-id"})'
356
357       Or to filter on message bodies with:
358
359         $ stompclt ... --callback-code 'return("skip") unless $bdy =~ /error/'
360

SUBSCRIPTIONS

362       In the case of an incoming broker, stompclt deals with the
363       subscriptions defined by the --subscribe option.
364
365       Regardless of the --reliable option, subscriptions are always made
366       using receipts. Also, if missing, an "id" header is always added.
367
368       Here is for instance how to create a named durable topic subscription
369       using Apollo:
370
371         $ stompclt ... --subscribe 'destination=/topic/foo persistent=true id=mysub'
372
373       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
377       If the --unsubscribe option is given, even if it is empty, stompclt
378       will explicitly unsubscribe before disconnecting, also using receipts.
379
380       Here is for instance how to destroy, when stompclt ends, the durable
381       topic subscription created above:
382
383         $ stompclt ... --unsubscribe 'persistent=true'
384
385       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

UDP SUPPORT

390       stompclt has experimental UDP support (outgoing only). This has been
391       tested with Apollo.
392
393       To use it, simply specify an outgoing URI that uses UDP such as:
394
395         $ stompclt ... --outgoing-broker-uri udp://broker.acme.com:6163
396
397       Features such as authentication, heart beating, reliability and socket
398       options are not supported over UDP.
399

EXAMPLES

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
407         # 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
427   RECEIVING
428       Here is an example of a configuration file for a message receiver
429       daemon (from broker to queue):
430
431         # 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
455       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
458         $ stompclt --config test.conf --no-daemon --timeout-inactivity 10
459
460   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
465         # 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
487   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
493         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
506       Callback data must be given to specify which message queue to use:
507
508         $ stompclt --config tap.conf --callback-data "path=/tmp/tap type=DQS"
509

SEE ALSO

511       Authen::Credential, Config::General, Messaging::Message,
512       Messaging::Message::Queue, Net::STOMP::Client.
513

AUTHOR

515       Lionel Cons <http://cern.ch/lionel.cons>
516
517       Copyright (C) CERN 2012-2019
518
519
520
521perl v5.30.0                      2019-07-27                       STOMPCLT(1)
Impressum