1imqcmd(1M) System Administration Commands imqcmd(1M)
2
3
4
6 imqcmd - manage Message Queue brokers
7
9 /usr/bin/imqcmd subcommand argument [option...]
10
11
12 /usr/bin/imqcmd [-h | -H]
13
14
15 /usr/bin/imqcmd -v
16
17
19 imqcmd manages the Message Queue broker, including resources such as
20 connection services, physical destinations, durable subscriptions, and
21 transactions. The utility provides a number of subcommands for managing
22 these resources.
23
24
25 imqcmd supports many subcommands. Basic connection and authentication
26 is required for the execution of every imqcmd subcommand. Use the
27 -secure option to specify secure connections. Subcommands and their
28 corresponding arguments and options follow the imqcmd command on the
29 command line. See USAGE and OPTIONS.
30
32 The following options are supported:
33
34 -b hostName:port Specify the name of the host on which the broker
35 instance is running and the port number it is
36 using.
37
38 The default value is localhost:7676. If you do
39 not specify the -b option, imqcmd uses the
40 default.
41
42 To specify port only, use: -b :7878. This is
43 equivalent to -b localhost:7878
44
45 To specify name only, use: -b somehost. This is
46 equivalent to -b somehost:7676.
47
48
49 -c clientID Specify the ID of the durable subscriber to a
50 topic.
51
52
53 -d topicName Specify the name of the topic.
54
55 Use this option with the list dur and destroy dur
56 subcommands.
57
58
59 -f Perform action without user confirmation.
60
61 Use this option with any subcommand.
62
63
64 -h Display usage help. Execute nothing else on the
65 command line.
66
67
68 -H Display usage help, attribute list, and examples.
69 Execute nothing else on the command line.
70
71
72 -int interval Specify the interval, in seconds, at which the
73 metrics bkr, metrics dst, and metrics svc subcom‐
74 mands display metrics output.
75
76 Use this option with the metrics subcommand.
77
78
79 -javahome Specify an alternate Java 2 compatible runtime to
80 use.
81
82
83 -m metricType Specify the type of metric information to diplay.
84
85 Use this option with the metrics bkr, metrics
86 dst, and metrics svc subcommands. The value of
87 metricType depends on whether the metrics are
88 generated for a destination, a service, or a bro‐
89 ker.
90
91 Use one of the following values to specify met‐
92 ricType:
93
94 ttl Total of messages in and out of the broker
95 (default)
96
97
98 rts Provides the same information as ttl, but
99 specifies the number of messages per sec‐
100 ond
101
102
103 cxn Connections, virtual memory heap, threads
104
105 The following command displays connection, VM
106 heap, and threads metric information for the
107 default broker instance (localhost:7676) every
108 five seconds:
109
110 imqcmd metrics bkr -m cxn -int 5
111
112
113
114
115 -msp numSamples Specify the number of samples the metrics bkr,
116 metrics dst, and metrics svc subcommands display
117 in the metrics output.
118
119
120 -n argumentName Specify the name of the subcommand argument.
121 Depending on the subcommand, this might be the
122 name of a service, a physical destination, a
123 durable subscription, or a transaction ID.
124
125
126 -o attribute=value Specify the value of an attribute. Depending on
127 the subcommand argument, this might be the
128 attribute of a broker, service, or destination.
129
130
131 -p password Specify the administrator password.
132
133 This option is deprecated. Use the -passfile
134 option instead.
135
136
137 -passfile Specify the administrator password.
138
139
140 -pst pauseType Specify whether producers, consumers, or both are
141 paused when pausing a destination.
142
143 Use this option with the pause dst subcommand.
144 Use one of the following values:
145
146 CONSUMERS Pause delivery of messages to con‐
147 sumers.
148
149
150 PRODUCERS Pause delivery of messages from pro‐
151 ducers.
152
153
154 ALL Pause delivery of messages to con‐
155 sumers and from producers.
156
157 If the -pst option is not specified, pauses both
158 consumers and producers (the equivalent of -pst
159 ALL).
160
161
162 -rtm timeout Specify the timeout period in seconds of an
163 imqcmd subcommand. The default value is 10.
164
165
166 -rtr numRetries Specify the number of retries attempted after an
167 imqcmd subcommand times out.
168
169 The default value is 5.
170
171
172 -s Silent mode. No output is displayed.
173
174 Use this option with any subcommand.
175
176
177 -secure Specify a secure administration connection to the
178 broker instance. You must first configure the
179 broker to enable a secure connection service.
180
181 Use this option whenever you want a secure commu‐
182 nication with the broker.
183
184
185 -svn serviceName Specify the service for which the connections are
186 listed.
187
188 Use this option with the list cxn subcommand.
189
190
191 -t destinationType Specify the type of a destination: t (topic) or q
192 (queue).
193
194
195 -tmp Include temporary destinations when listing des‐
196 tinations using the list dst subcommand.
197
198
199 -u name Specify the administrator user name.
200
201 If you omit this value, you are prompted for it.
202
203
204 -v Display version information. Execute nothing else
205 on the command line.
206
207
209 Subcommands and Options
210 The following subcommands and associated arguments and options are sup‐
211 ported:
212
213 compact dst [-t type -n destName]
214
215 Compact the flat-file data store for the destination of the speci‐
216 fied type and name. If no type and name are specified, all destina‐
217 tions are compacted. Destinations must be paused before they can be
218 compacted.
219
220
221 commit txn -n transaction_id
222
223 Commit the specified transaction
224
225
226 create dst -t destinationType -n destName [-o attribute=value] [-o
227 attribute=value1]...
228
229 Create a destination of the specified type, with the specified
230 name, and the specified attributes. Destination names must contain
231 only alphanumeric characters (no spaces) and can begin with an
232 alphabetic character or the underscore character (_).
233
234
235 destroy dst -t destinationType -n destName
236
237 Destroy the destination of the specified type and name.
238
239
240 destroy dur -n subscrName -c client_id
241
242 Destroy the specified durable subscription for the specified Client
243 Identifier.
244
245
246 list cxn [-svn serviceName] [-b hostName:port]
247
248 List all connections of the specified service name on the default
249 broker or on a broker at the specified host and port. If the ser‐
250 vice name is not specified, all connections are listed.
251
252
253 list dst [-tmp]
254
255 List all destinations, with option of listing temporary destina‐
256 tions as well .
257
258
259 list dur -d destination
260
261 List all durable subscriptions for the specified destination.
262
263
264 list svc
265
266 List all connection services on the broker instance.
267
268
269 list txn
270
271 List all transactions, being tracked by the broker.
272
273
274 metrics bkr [-m metricType] [-int interval] [-msp numSamples]
275
276 Display broker metrics for the broker instance.
277
278 Use the -m option to specify the type of metric to display. Use one
279 of the following values to specify metricType:
280
281 ttl Specifies the total of messages in and out of the broker
282 (default) .
283
284
285 rts Provides the same information as ttl, but specifies the num‐
286 ber of messages per second.
287
288
289 cxn Connections, virtual memory heap, threads.
290
291 Use the -int option to specify the interval (in seconds) at which
292 to display the metrics. The default is 5 seconds.
293
294 Use the -msp option to specify the number of samples displayed in
295 the output. A value of -1 means an unlimited number. The default
296 value is -1.
297
298
299 metrics dst -t type -n destName [-m metricType] [-int interval] [-msp
300 numSamples]
301
302 Displays metrics information for the destination of the specified
303 type and name.
304
305 Use the -m option to specify the type of metrics to display. Use
306 one of the following values to specify metricType:
307
308 ttl Specifies the number of messages flowing in and out of the
309 broker and residing in memory.
310
311
312 rts Provides the same information as ttl, but specifies the num‐
313 ber of messages per second.
314
315
316 con Displays consumer related metrics.
317
318
319 dsk Displays disk usage metrics.
320
321 Use the -int option to specify the interval (in seconds) at which
322 to display the metrics. The default is 5 seconds.
323
324 Use the -msp option to specify the number of samples displayed in
325 the output. A value of -1 means an unlimited number. The default
326 value is 5.
327
328
329 metrics svc -n serviceName [-m metricType] [-int interval] [-msp num‐
330 Samples]
331
332 List metrics for the specified service on the broker instance. Use
333 the -m option to specify the type of metric to display. Use one of
334 the following values to specify metricType:
335
336 ttl Total of messages in and out of the broker (default)
337
338
339 rts Provides the same information as ttl, but specifies the num‐
340 ber of messages per second
341
342
343 cxn Connections, virtual memory heap, threads
344
345 Use the -int option to specify the interval (in seconds) at which
346 to display the metrics. The default is 5 seconds.
347
348 Use the -msp option to specify the number of samples displayed in
349 the output. A value of -1 means an unlimited number. The default
350 value is -1.
351
352
353 pause bkr
354
355 Pause the broker instance.
356
357
358 pause dst [-t type -n destName] [-pst pauseType]
359
360 Pause the delivery of messages to consumers (-pst CONSUMERS), or
361 from producers (-pst PRODUCERS), or both (-pst ALL), for the desti‐
362 nation of the specified type and name. If no destination type or
363 name are specified, all destinations are paused.
364
365
366 pause svc -n serviceName
367
368 Pause the specified service running on the broker instance. You
369 cannot pause the administative service.
370
371
372 purge dst -t destinationType -n destName
373
374 Purge messages at the destination with the specified type and name.
375
376
377 purge dur -n subscrName -c client_id
378
379 Purge all messages for the specified client identifier.
380
381
382 query bkr
383
384 List the current settings of properties of the broker instance.
385 Show the list of running brokers (in a multi-broker cluster) that
386 are connected to the specified broker.
387
388
389 query dst -t destinationType -n destName
390
391 List information about the destination of the specified type and
392 name.
393
394
395 query svc -n serviceName
396
397 Display information about the specified service running on the bro‐
398 ker instance.
399
400
401 query txn -n transaction_id
402
403 List information about the specified transaction.
404
405
406 reload cls
407
408 Forces all the brokers in a cluster to reload the imq.cluster.bro‐
409 kerlist property and update cluster information. This subcommand
410 only applies to broker clusters.
411
412
413 restart bkr
414
415 Shut down and restart the broker instance. This command restarts
416 the broker using the options specified when the broker was first
417 started. If you want different options to be in effect, you must
418 shut down the broker and then start it again, specifying the
419 options you want.
420
421
422 resume bkr
423
424 Resume the broker instance.
425
426
427 resume dst [-t type] [-n -destName]
428
429 Resumes the delivery of messages for the paused destination of the
430 specified type and name. If no destination type and name are speci‐
431 fied, all destinations are resumed.
432
433
434 resume svc -n serviceName
435
436 Resume the specified service running on the broker instance.
437
438
439 rollback txn -n transaction_id
440
441 Roll back the specified transaction.
442
443
444 shutdown bkr
445
446 Shut down the broker instance
447
448
449 update bkr -o attribute=value [-o attribute=value]...
450
451 Change the specified attributes for the broker instance.
452
453
454 update dst -t destinationType -n destName -o attribute=value [-o
455 attribute=value1]...
456
457 Update the value of the specified attributes at the specified des‐
458 tination..
459
460
461 update svc -n serviceName -o attribute=value [-o attribute=value1]...
462
463 Update the specified attribute of the specified service running on
464 the broker instance.
465
466
467 Attribute Value Pairs
468 You can specify attributes with the create and update subcommands.
469 Applicable attributes depend on the subcommand arguments.
470
471
472 The following attributes are supported:
473
474
475 Queue (dst):
476
477 maxTotalMsgBytes Value: Integer (maximum total size of mes‐
478 sages, in bytes)
479
480 Default: 0 (unlimited)
481
482
483 maxBytesPerMsg Value: Integer (maximum size of a single mes‐
484 sage, in bytes)
485
486 Default: 0 (unlimited)
487
488
489 maxNumMsgs Value: Integer (maximum total number of mes‐
490 sages)
491
492 Default: 0 (unlimited)
493
494
495 consumerFlowLimit Value: Integer Initial number of queued mes‐
496 sages sent to active consumers before load-
497 balancing starts A value of -1 means an
498 unlimited number.
499
500 Default: 1000
501
502
503 isLocalOnly Value: Boolean (destination limited to deliv‐
504 ering messages to local consumers only)
505 Default: false
506
507
508 limitBehavior Value: Specify how broker responds when mem‐
509 ory-limit is reached. Use one of the follow‐
510 ing values:
511
512 FLOW_CONTROL Slows down producers
513
514
515 REMOVE_OLDEST Purges oldest messages
516
517
518 REJECT_NEWEST Rejects the newest messages
519
520 Default: REJECT_NEWEST
521
522
523 localDeliveryPreferred Value: Boolean Specify messages be delivered
524 to remote consumers only if there are no con‐
525 sumers on the local broker. Requires that the
526 destination not be restricted to local-only
527 delivery (isLocalOnly = false)
528
529 Default: false
530
531
532 maxNumActiveConsumers Value: Integer (maximum number of active con‐
533 sumers in load-balanced delivery) A value of
534 -1 means an unlimited number.
535
536 Default: 1
537
538
539 maxNumBackupConsumers Value: Integer (maximum number of backup con‐
540 sumers in load-balanced delivery) A value of
541 -1 means an unlimited number.
542
543 Default: 0
544
545
546 maxNumProducers Value: (maximum total number of producers) A
547 value of -1 means an unlimited number.
548
549 Default: -1
550
551
552 useDMQ Specify whether a destination's dead messages
553 are discarded or put on the dead message
554 queue.
555
556 Default: true
557
558
559
560 Topic (dst):
561
562 consumerFlowLimit Value: Integer Maximum number of messages deliv‐
563 ered to a consumer in a single batch. A value of
564 -1 means an unlimited number.
565
566 Default: 1000
567
568
569 isLocalOnly Value: Boolean (destination limited to delivering
570 messages to local consumers only)
571
572 Default: false
573
574
575 limitBehavior Value: Specify how broker responds when memory-
576 limit is reached. Use one of the following values:
577
578 FLOW_CONTROL Slows down producers
579
580
581 REMOVE_OLDEST Purges the oldest messages
582
583
584 REJECT_NEWEST Rejects the newest messages
585
586 Default: REJECT_NEWEST
587
588
589 maxBytesPerMsg Value: Integer (maximum size of a single message,
590 in bytes)
591
592 Default: 0 (unlimited)
593
594
595 maxNumMsgs Value: Integer (maximum total number of messages)
596 A value of -1 means an unlimited number.
597
598 Default: -1
599
600
601 maxNumProducers Value: (maximum total number of producers)
602
603 Default: 0 (unlimited)
604
605
606 maxTotalMsgBytes Value: Integer (maximum total size of messages, in
607 bytes) A value of -1 means an unlimited number.
608
609 Default: -1
610
611
612 useDMQ Specify whether a destination's dead messages are
613 discarded or put on the dead message queue.
614
615 Default: true
616
617
618
619 Broker (bkr):
620
621 imq.autocreate.destination.useDMQ
622
623 Value: Boolean. Set the useDMQ attribute to true to enable all
624 autocreated physical destinations on a broker to use the dead mes‐
625 sage queue. Set the useDMQ attribute to false to disable all
626 autocreated physical destinations on a broker from using the dead
627 message queue.
628
629 Default: true
630
631
632 imq.autocreate.queue
633
634 Value: Boolean
635
636 Default: true
637
638
639 imq.autocreate.queue.maxNumActiveConsumers
640
641 Value: Integer (maximum number of consumers that can be active in
642 load-balanced delivery from an autocreated queue destination) A
643 value of -1 means an unlimited number.
644
645 Default: 1
646
647
648 imq.autocreate.queue.maxNumBackupConsumers
649
650 Value: Integer (maximum number of backup consumers that can take
651 the place of active consumers) A value of -1 means an unlimited
652 number.
653
654 Default: 0
655
656
657 imq.autocreate.topic
658
659 Value: Boolean
660
661 Default: true
662
663
664 imq.cluster.url
665
666 Value: String (location of cluster configuration file)
667
668 Default: none
669
670
671 imq.log.file.rolloverbytes
672
673 Value: Integer (maximum size of a log file, in bytes)
674
675 Default: 0 (no rollover based on size)
676
677
678 imq.log.file.rolloversecs
679
680 Value: Integer (maximum age of a log file, in seconds)
681
682 Default: 0 (no rollover based on age)
683
684
685 imq.log.level
686
687 Value: String (NONE, ERROR, WARNING, INFO)
688
689 Default: INFO
690
691
692 imq.message.max_size
693
694 Value: Integer (maximum size of a single message, in bytes)
695
696 Default: 70m
697
698
699 imq.portmapper.port
700
701 Value: Integer
702
703 Default: 7676
704
705
706 imq.system.max_count
707
708 Value: Integer (maximum total number of messages)
709
710 Default: 0 (no limit)
711
712
713 imq.system.max_size
714
715 Value: Integer (maximum total size of messages, in bytes)
716
717 Default: 0 (no limit)
718
719
720
721 Service (svc):
722
723 maxThreads Value: Integer (maximum threads assigned)
724
725 Default: Depends on service
726
727
728 minThreads Value: Integer (minimum threads assigned)
729
730 Default: Depends on service
731
732
733 port Value: Integer
734
735 Default: 0 (dynamically allocated)
736
737
739 Example 1 Shutting Down a Broker
740
741
742 The following command shuts down a broker for hostname myserver on port
743 7676:
744
745
746 mqcmd shutdown bkr -b myserver:7676
747
748
749
750 Example 2 Restarting a Broker
751
752
753 The following command restarts a broker for hostname myserver:
754
755
756 imqcmd restart bkr -b myserver
757
758
759
760 Example 3 Pausing a Service
761
762
763 The following command pauses a broker for hostname localhost on port
764 7676, with a serviceName of jms:
765
766
767 imqcmd pause svc -n jms -b :7676
768
769
770
771 Example 4 Resuming a Service
772
773
774 The following command resumes a service for hostname localhost on port
775 7676, with a serviceName of jms:
776
777
778 imqcmd resume svc -n jms -b myserver:7676
779
780
781
782 Example 5 Creating a Queue Destination
783
784
785 The following command creates a queue destination for hostname myserver
786 on port 7676, with a destName of myFQ, a queueDeliveryPolicy of
787 Failover, and a maxBytesPerMsg of 10000:
788
789
790 imqcmd create dst -n myFQ -t q -o "queueDeliveryPolicy=f" \
791 -o "maxBytesPerMsg=10000" -b myserver:7676
792
793
794
795 Example 6 Purging a Queue Destination
796
797
798 The following command purges a queue destination for hostname myserver
799 on port 7676, with a destName of myFQ:
800
801
802 imqcmd purge dst -n myFQ -t q -b myserver:7676
803
804
805
806 Example 7 Listing Destinations on a Broker
807
808
809 The following command lists destinations for hostname myserver on port
810 7676:
811
812
813 imqcmd list dst -b myserver:7676
814
815
816
817 Example 8 Updating a Portmapper Port
818
819
820 The following command updates a portmapper port on hostname myserver
821 from port 7676 to 7878:
822
823
824 imqcmd update bkr -o "imq.portmapper.port=7878"
825
826
827
828 Example 9 Updating the Maximum Number of Messages in the Queue
829
830
831 The following command updates the maximum number of messages in the
832 queue to 2000 for myserver on port 8080 with a destName of TestQueue:
833
834
835 imqcmd update dst -b myserver:8080 -n TestQueue -t q -o "maxNumMsgs=2000"
836
837
838
839 Example 10 Updating the Maximum Threads
840
841
842 The following command updates the maximum threads jms connection ser‐
843 vice to 200 for hostname localhost on port 7676:
844
845
846 imqcmd update svc -n jms -o "minThreads=200"
847
848
849
850 Example 11 Listing Durable Subscriptions
851
852
853 The following command lists durable subscriptions for a topic with
854 hostname localhost on port 7676 with a destName of myTopic:
855
856
857 imqcmd list dur -d myTopic
858
859
860
861 Example 12 Destroying Durable Subscriptions
862
863
864 The following command destroys subscriptions for hostname localhost on
865 port 7676 with a dursubName of myDurSub and a client_ID of
866 111.222.333.444:
867
868
869 imqcmd destroy dur -n myDurSub -c "111.222.333.444"
870
871
872
873 Example 13 Listing All Transactions
874
875
876 The following command lists all transactions on a broker with hostname
877 localhost on port 7676:
878
879
880 imqcmd list txn
881
882
883
884 Example 14 Displaying Information About a Transaction
885
886
887 The following command displays information about a transaction with
888 hostname localhost on port 7676, and a transactionID of 1234567890
889
890
891 imqcmd query txn -n 1234567890
892
893
894
895 Example 15 Committing a Transaction
896
897
898 The following command commits a transaction with hostname localhost on
899 port 7676, and a transactionID of 1234567890:
900
901
902 imqcmd commit txn -n 1234567890
903
904
905
907 The following environment variables affect the execution of this com‐
908 mand:
909
910 IMQ_JAVAHOME Specify the Java 2 compatible runtime. When this envi‐
911 ronment variable is not set it defaults to /usr/j2se.
912
913
915 The following exit values are returned:
916
917 0 Successful completion.
918
919
920 >0 An error occurred.
921
922
924 See attributes(5) for descriptions of the following attributes:
925
926
927
928
929 ┌─────────────────────────────┬─────────────────────────────┐
930 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
931 ├─────────────────────────────┼─────────────────────────────┤
932 │Availability │SUNWiqu │
933 └─────────────────────────────┴─────────────────────────────┘
934
936 imqadmin(1M), imqbrokerd(1M), imqdbmgr(1M), imqkeytool(1M), imqob‐
937 jmgr(1M), imqusermgr(1M), attributes(5)
938
939
940 Sun Java System Message Queue Administrator's Guide
941
942
943
944SunOS 5.11 7 Aug 2007 imqcmd(1M)