1imqcmd(1M)              System Administration Commands              imqcmd(1M)
2
3
4

NAME

6       imqcmd - manage Message Queue brokers
7

SYNOPSIS

9       /usr/bin/imqcmd subcommand argument [option...]
10
11
12       /usr/bin/imqcmd [-h | -H]
13
14
15       /usr/bin/imqcmd -v
16
17

DESCRIPTION

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

OPTIONS

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

USAGE

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

EXAMPLES

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

ENVIRONMENT VARIABLES

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

EXIT STATUS

915       The following exit values are returned:
916
917       0     Successful completion.
918
919
920       >0    An error occurred.
921
922

ATTRIBUTES

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

SEE ALSO

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)
Impressum