|
| Sun ONE Message Queue, Version 3.0.1 管理员指南 |
本章介绍如何执行与管理代理及其提供的服务相关的任务。某些任务并不是针对特定的客户机应用程序。这些任务包括：
- 控制代理的状态：可以暂停、恢复、关闭和重新启动代理。
- 查询和更新代理属性
- 查询和更新连接服务
- 分配和管理资源
- 管理连接服务
其它代理任务是在特定应用程序上执行的，包括管理物理目标、长期订阅和事务等任务：
- MQ 消息通过代理目标路由到接收者或订户。您负责在代理上创建这些目标。
- MQ 负责为长期订户分配并维护资源，即使这些客户机的长期订阅处于非活动状态。使用 MQ 命令工具可以获得长期订阅的相关信息，也可以销毁长期订阅或清理其中的消息以节约 MQ 资源。
- MQ 事务和分布式事务由代理来跟踪。如果出现错误，可能需要手动提交或回滚事务。
本章介绍如何使用命令行实用程序 (imqcmd) 来执行这些任务。许多任务还可以使用管理控制台（MQ 消息服务器的图形界面）来完成。有关详细信息，请参阅第 4 章“管理控制台教程”。
命令行实用程序
命令行实用程序可用于管理代理及其提供的服务。本节介绍了基本的 imqcmd 命令语法，提供了一个子命令列表，并概述了 imqcmd 的选项。后续各节将介绍如何使用这些命令完成特定的任务。
命令语法
imqcmd 命令的一般语法如下：
imqcmd subcommand argument [options]
imqcmd -h|H
imqcmd -v请注意，如果指定 -v、-h 或 -H 选项，将不会执行命令行中指定的子命令。例如，输入以下命令将显示版本信息，而不是执行 restart 子命令。
imqcmd restart bkr -v
imqcmd 子命令
表 6-1 列出了命令行实用程序 (imqcmd) 包含的子命令：
imqcmd 选项概述
表 6-2 列出了 imqcmd 命令的选项。有关如何使用它们的讨论，请参阅后面针对具体任务的各节。
表 6-2 imqcmd 选项
选项
说明
-b hostName:port
指定代理的主机名和端口号。默认值为 localhost:7676。
要仅指定端口，请使用：-b :7878
要仅指定主机名，请使用：-b 某台主机-c clientID
指定订阅某个主题的长期订户的 ID。有关详细信息，请参阅管理长期订阅。
-d topicName
指定主题的名称。与 list dur 和 destroy dur 子命令一起使用。请参阅管理长期订阅。
-f
执行操作，无需用户确认。
-h
显示使用帮助。不执行命令行上的命令。
-H
显示使用帮助、属性列表和实例。不执行命令行上的命令。
-int interval
指定 imqcmd 显示代理标准的时间间隔，以秒为单位。（与 metrics 子命令一起使用。）
-javahome
指定可使用的替代 Java 2 兼容运行时（默认使用产品附带的运行时）。
-m metricType
指定要显示的标准类型。可以是下列类型之一：
ttl 流入和流出代理的所有消息（默认）。
rts 与 ttl 提供相同的信息，但指定了每秒钟的消息数量。
cxn 连接、虚拟内存堆、线程。
与 metrics bkr 或 metrics svc 子命令一起使用。以下命令每隔五秒钟显示一次默认代理的 cxn 类型的标准。
imqcmd metrics bkr -m cxn -int 5
-n argumentName
指定子命令参数的名称。根据子命令的不同，它可能是服务名称、物理目标、长期订阅或
事务 ID。-o attribute=value
指定属性的值。根据子命令参数的不同，它可能是代理属性（请参阅查询和更新代理属性）、服务属性（请参阅管理连接服务）或目标属性（请参阅管理目标）。
-secure
使用 ssladmin 连接服务指定代理的安全管理连接（请参阅步骤 4：配置并运行基于 SSL 的客户机，命令行实用程序 (imqcmd)）。
-p password
指定管理员的密码。如果省略此值，系统会提示您输入密码。
-s
无提示模式。不显示任何输出。
-t destinationType
指定目标的类型：t（主题）或 q（队列）。
-tmp
显示临时目标。
-u name
指定管理员的用户名。如果省略此值，系统会提示您输入用户名。
-v
显示版本信息。不执行命令行上的命令。
每次发出一个 imqcmd 子命令时，都必须指定以下选项：主机名和端口号 (-b)、用户名 (-u)、密码 (-p) 和安全连接 (-secure)。如果不指定主机名和端口号，系统将使用默认值。如果不指定用户名和密码，系统会提示您输入这些信息。如果不指定 -secure，连接将是不安全的。
使用 imqcmd 的前提条件
要使用 imqcmd 命令管理代理，必须执行以下操作：
- 使用 imqbrokerd 命令启动代理。
请参阅启动代理。命令行实用程序只能用于管理正在运行的代理，不能用于启动代理。
- 如果代理没有在本地主机的 7676 端口上运行，必须使用 -b 选项指定目标代理。
- 指定适当的管理员用户名和密码。如果不指定，系统会提示您输入这些信息。总之请记住，使用 imqcmd 执行的每一个操作都要在用户系统信息库中进行验证。
安装 MQ 时，系统会安装默认的用户系统信息库，这是一个纯文本文件。文件名为 IMQ_HOME/etc/passwd（在 Solaris 操作系统中为 /etc/imq/passwd）。系统信息库出厂时包括两个条目：一个供管理员用户使用，另一个供临时用户使用。使用这两个条目即可建立代理连接，无需执行额外的操作。例如，如果只是要测试 MQ，可以使用默认的用户名和密码 (admin/admin) 来运行实用程序。
如果要设置生产系统，则需要完成一些额外的工作，对用户进行验证和授权。也可以将现有的 LDAP 目录服务器作为用户系统信息库。有关详细信息，请参阅验证用户。
实例
以下命令将列出运行在 localhost 7676 端口上的代理的属性：
imqcmd query bkr -u admin -p admin
以下命令将列出运行在 myserver 7676 端口上的代理的属性，用户名为 alladin，密码为 abracadabra。
imqcmd query bkr -b myserver:1564 -u alladin -p abracadabra
如果指定用户名 alladin 属于 admin 组，将以管理员客户机的身份连接到指定代理。
控制代理的状态
启动代理后，可以使用下列 imqcmd 子命令控制其状态。
- 暂停代理
暂停代理将暂停代理服务线程，从而使代理停止监听端口。然后您可以执行控制代理消息流所需的管理任务。例如，当某个目标受到消息攻击时，您可以暂停该代理，然后执行下列操作之一，以期解决该问题：跟踪消息来源、限制目标的大小或销毁目标。
以下命令将暂停运行在 myhost 1588 端口上的代理。
imqcmd pause bkr -b myhost:1588
- 恢复代理
恢复代理将重新激活代理服务线程，从而使代理恢复监听端口。以下命令将恢复运行在 localhost 7676 端口上的代理。
imqcmd resume bkr
- 关闭代理
关闭代理将终止代理进程。这属于正常终止：代理停止接收新的连接和消息，完成现有消息的传送后将终止代理进程。以下命令将关闭运行在 ctrlsrv 1572 端口上的代理。
imqcmd shutdown bkr -b ctrlsrv:1572
- 重新启动代理
关闭并重新启动代理。以下命令将重新启动运行在 localhost 7676 端口上的代理。
imqcmd restart bkr
表 6-3 概述了用于控制代理的 imqcmd 子命令。请记住，除非您希望代理在 localhost 7676 端口上运行，否则必须指定代理主机名和端口号。
查询和更新代理属性
命令行实用程序包含的子命令可用于获取代理信息、更新代理属性。表 6-4 列出了这些子命令。
表 6-4 用于获取代理信息和更新代理的 imqcmd 子命令
子命令语法
说明
query bkr -b hostName:port
列出默认代理或指定主机和端口上的代理的当前属性设置。还将列出与指定代理连接且正在运行的代理（在多代理群集中）。
reload cls
仅适用于代理群集。强制群集中的所有代理重新装入 imq.cluster.brokerlist 属性并更新群集信息。有关详细信息，请参阅将代理添加到群集。
update bkr [-b hostName:port]
-o attribute=value
[-o attribute=value1]...
更改默认代理或指定主机和端口上的代理的指定属性。
metrics bkr [-b hostName:port]
[-m metricType]
[-int interval]
显示默认代理或指定主机和端口上的代理的代理标准。
使用 -m 选项指定要显示的标准类型：
ttl 流入和流出代理的所有消息（默认）。
rts 与 ttl 提供相同的信息，但指定了每秒钟的消息数量。
cxn 连接、虚拟内存堆、线程。
使用 -int 选项指定显示标准的时间间隔（以秒为单位）。默认值为 5 秒。
请记住，使用表 6-4 中列出的子命令时，除非您希望代理在 localhost 7676 端口上运行，否则必须指定代理主机名和端口号。
查询代理
要查询并显示某个代理的信息，请使用 query 子命令。例如：
imqcmd query bkr
此语句的输出如下：
%imqcmd query bkr
Querying the broker specified by:
-------------------------
Host Primary Port
-------------------------
localhost 7676
Auto Create Queues true
Auto Create Topics true
Auto Created Queue Delivery Policy Round Robin
Cluster Broker List (active) myhost/192.18.116.221:7676
Cluster Broker List (configured)
Cluster Master Broker
Cluster URL
Current Number of Messages in System 0
Current Size of Messages in System 0
Instance Name imqbroker
Log Level INFO
Log Rollover Interval (seconds) 604800
Log Rollover Size (bytes) 0 (unlimited)
Max Message Size 70m
Max Number of Messages in System 0 (unlimited)
Max Size of Messages in System 0 (unlimited)
Primary Port 7676
Version 3.0
Successfully queried the broker.
更新代理
可以使用 update 子命令更新表 6-5 中列出的任何代理属性。请注意，对代理的更新会自动写入代理的实例配置文件。
表 6-5 代理属性
属性
说明
imq.autocreate.queue
指定是否允许代理自动创建队列目标。默认值为 True。
imq.autocreate.topic
指定是否允许代理自动创建主题目标。默认值为 True。
imq.queue.deliverypolicy
为自动创建的队列指定默认传送策略。有效值包括：s（单向）、
r（循环）或 f（故障切换）。默认值为 s。imq.cluster.url
指定群集配置文件的位置。有关详细信息，请参阅群集配置属性。
imq.log.level
指定下列日志级别之一：NONE、ERROR、WARNING 或 INFO。默认值为 INFO。
imq.log.file.rolloversecs
日志文件转移前的生存期（以秒为单位）。0 表示不发生基于文件生存期的转移。默认值为 604800 秒（7 天）。
imq.log.file.rolloverbytes
指定日志文件转移前的最大文件大小。0 表示不发生基于文件大小的转移。默认值为 0。
imq.message.max_size
指定消息的最大大小（以字节为单位）。默认值为 70m。
imq.system.max_count
指定内存和磁盘中的最大消息数量。0 表示没有限制。默认值为 0。
imq.system.max_size
指定内存和磁盘中所有消息总大小的最大值。0 表示没有限制。默认值为 0。
imq.portmapper.port
指定端口映射器的端口号。默认值为 7676。
例如，以下命令会将队列的默认传送策略由单向改为循环。
imqcmd update bkr -o "imq.queue.deliverypolicy=r"
管理连接服务
命令行实用程序包括许多子命令，您可以使用这些子命令执行以下操作：
- 列出可用的连接服务
- 显示某项特定服务的信息
- 更新某项服务的属性
- 暂停和恢复服务
有关 MQ 连接服务的概述信息，请参阅连接服务。
表 6-6 列出了控制连接服务的 imqcmd 子命令。如果没有指定主机名和端口，则假定为 localhost 和 7676。
表 6-6 用于管理连接服务的 imqcmd 子命令
子命令语法
说明
list svc [-b hostName:port]
列出默认代理或指定主机和端口上的代理中的所有连接服务。
metrics svc -n serviceName
[-b hostName:port]
[-m metricType] [-int interval]
列出默认代理或指定主机和端口上的代理中指定服务的标准。
使用 -m 选项指定要显示的标准类型：
ttl 流入和流出代理的所有消息（默认）。
rts 与 ttl 提供相同的信息，但指定了每秒钟的消息数量。
cxn 连接、虚拟内存堆、线程。
使用 -int 选项指定显示标准的时间间隔（以秒为单位）。默认值为 5 秒。
query svc -n serviceName
[-b hostName:port]
显示运行在默认代理或指定主机和端口上的代理中的指定服务的信息。
pause svc -n serviceName
[-b hostName:port]
暂停运行在默认代理或指定主机和端口上的代理中的指定服务。不能暂停管理服务。
resume svc -n serviceName
[-b hostName:port]
恢复运行在默认代理或指定主机和端口上的代理中的指定服务。
update svc -n serviceName
[-b hostName:port]
-o attribute=value
[-o attribute=value1]...
更新运行在默认代理或指定主机和端口上的代理中的指定服务的指定属性。有关服务属性的说明，请参阅表 6-8。
代理支持与应用程序客户机和管理客户机的通信。表 6-7 显示了 MQ 代理当前支持的连接服务。“服务名称”一栏中的值用于为 -n 选项指定服务名称。（正如该表所示，每项服务都是通过它使用的服务类型 — NORMAL(JMS) 或 ADMIN — 和底层传输层来指定的。）
列出连接服务
要列出某个代理支持的连接服务，请使用如下命令：
imqcmd list svc [-b 主机名：端口号]
例如，以下命令将列出运行在 MyServer 主机 6565 端口上的代理所支持的服务。
imqcmd list svc -b MyServer:6565
以下命令将列出运行在 localhost 7676 端口上的代理支持的所有服务：
imqcmd list svc
该命令的输出信息如下：
Listing all the services on the broker specified by:
Host Primary Port
localhost 7676
Service Name Port Number Service State
admin 33984 (dynamic) RUNNING
httpjms UNKNOWN
httpsjms - UNKNOWN
jms 33983 (dynamic) RUNNING
ssladmin dynamic UNKNOWN
ssljms dynamic UNKNOWN
Successfully listed services.
查询和更新服务属性
要查询并显示某项服务的信息，请使用 query 子命令。例如：
imqcmd query svc -n jms
此语句的输出如下：
Querying the service where:
Service Name
jms
On the broker specified by:
Host Primary Port
localhost 7676
Current Number of Allocated Threads 120
Current Number of Connections 20
Max Number of Threads 1000
Min Number of Threads 50
Port Number 42019 (dynamic)
Service Name jms
Service State RUNNING
Successfully queried the service.
可以使用 update 子命令更改表 6-8 中列出的一个或多个服务属性的值。
表 6-8 连接服务属性
属性
说明
port
为要更新的服务指定的端口（不适用于 httpjms 和 httpsjms）。
minThreads
为服务指定的最小线程数。
maxThreads
为服务指定的最大线程数。
以下命令将指定给 jms 服务的最小线程数更改为 20。
imqcmd update svc -n jms -o "minThreads=20"
暂停和恢复服务
要暂停除管理服务之外的其它服务（不能暂停管理服务），请使用如下命令：
imqcmd pause svc -n serviceName
要恢复某项服务，请使用如下命令：
imqcmd resume svc -n serviceName
管理目标
所有 MQ 消息都是通过在特定代理上创建的目标、队列和主题路由到其使用方客户机上的。您负责在代理上管理这些目标。管理任务包括使用命令行实用程序创建和销毁目标、列出目标、显示目标的相关信息以及清理消息。有关目标的介绍，请参阅物理目标。
表 6-9 概述了 imqcmd 目标子命令。如果不使用默认代理 (localhost:7676)，则必须指定主机名和端口。
表 6-9 用于管理目标的 imqcmd 子命令
子命令
说明
list dst [-tmp]
列出所有目标，后面的选项表示同时列出临时目标（请参阅临时目标）。
create dst -t type
-n destName
[-o attribute=value]
[-o attribute=value1]...
创建指定类型、名称和属性的目标。目标名称只能包含字母数字字符（不能包含空格），可以以字母字符或者字符“_”开头。
destroy dst -t type
-n destName
销毁指定类型和名称的目标。
purge dst -t type
-n destName
清理指定类型和名称的目标中的消息。
query dst -t type
-n destName
列出指定类型和名称的目标的相关信息。
update dst -t type
-n destName
-o attribute=value
[-o attribute=value1]...
更新指定目标上指定属性的值。
属性名称可以是表 6-10 中列出的任意属性。
创建目标
创建目标时，必须指定目标类型（主题或队列），如果需要，还要指定目标的属性值。这些属性的默认值是在代理的配置文件中设置的（请参阅配置文件）。
销毁目标将清理该目标中的所有消息并将该目标从代理上删除，此操作是不可恢复的。
表 6-10 列出了创建目标时，可以为每种目标类型设置的属性。
- 要创建队列目标，请输入如下命令：
imqcmd create dst -n myQueue -t q -o "queueDeliveryPolicy=f"
请注意，目标名称必须是有效的 Java 标识符。
- 要创建主题目标，请输入如下命令：
imqcmd create dst -n myTopic -t t -o "maxBytesPerMsg=5000"
获得目标的相关信息
要获得某个目标属性当前值的信息，请使用如下命令：
imqcmd query dst -t q -n XQueue
然后可以使用 update imqcmd 子命令更改一个或多个属性的值。
要列出特定代理（例如，运行在 myHost 4545 端口上的代理）中的所有目标，请使用如下命令：
imqcmd list dst -b myHost:4545
使用 list 命令时可以选择是否列出临时目标（使用 -tmp 选项）。临时目标是由客户机应用程序创建的，该应用程序需要一个目标来接收发送到其它客户机上的消息的回复（请参阅临时目标）。您不能销毁这些目标；只有当不再存在活动的消息使用方时，才能通过客户机应用程序的 API 调用来销毁。
更新目标
可以使用 update dst 子命令更改目标的属性，而使用 -o 选项指定要更新的属性。如果要更新多个属性，可以多次使用 -o 选项。例如，以下命令将 maxBytesPerMsg 属性更改为 1000，同时将 MaxNumMsgs 属性更改为 2000：
imqcmd update dst -t q -n myQueue -o "maxBytesPerMsg=1000"
-o maxNumMsgs=2000要获得可以更新的属性列表，请参阅表 6-10。
不能使用 update dst 子命令更新目标的 type 属性或队列的队列传送策略。
清理目标
可以清理某个目标上当前排队的所有消息。清理目标意味着物理目标上排队的所有消息都将被删除。当目标中堆积的消息占用了大量系统资源时，您可能需要清理掉这些消息。这可能发生在某个队列没有注册使用方客户机，但仍在接收大量消息的情况下。也可能发生在某个主题的长期订户始终处于非活动状态的情况下。在上述两种情况下，都没有必要保留消息。
要清理目标上的消息，请输入如下命令：
imqcmd purge dst -n myQueue -t q
imqcmd purge dst -n myTopic -t t
如果关闭代理后不希望重新启动时传送旧消息，可以使用 imqbrokerd 命令的 reset 子命令将这些旧消息清理掉，如下所示：
imqbrokerd -reset messages
这样可以避免重新启动代理后清理目标的麻烦。
销毁目标
要销毁目标，请输入如下命令：
imqcmd destroy dst -t q -n myQueue
管理长期订阅
要管理代理的长期订阅，可以使用 imqcmd 子命令。长期订阅是指某台客户机长期注册订阅某个主题；长期订阅有一个唯一标识，要求代理保留该订阅的消息，即使消息使用方处于非活动状态。通常情况下，代理只能在消息已过期的情况下删除为长期订户保留的消息。
表 6-12 概述了 imqcmd 长期订阅子命令。如果不使用默认代理 (localhost:7676)，则必须指定主机名和端口。
表 6-11 用于管理长期订阅的 imqcmd 子命令
子命令
说明
list dur -d destination
列出指定目标的所有长期订阅。
destroy dur -n subscrName
-c client_id
销毁指定客户机 ID 的指定长期订阅（请参阅客户机标识符）。
purge dur -n subscrName
-c client_id
清理指定客户机 ID 的所有消息（请参阅客户机标识符）。
例如，以下命令将列出 SPQuotes 主题下的所有长期订阅：
imqcmd list dur -d SPQuotes
对于某个主题下的每个长期订阅，list 子命令将返回长期订阅的名称、用户的客户机 ID、该主题下排队的消息数量以及该长期订阅的状态（活动/非活动）。例如：
Listing all the durable subscriptions on the topic myTopic
on the broker specified by:
-------------------------
Host Primary Port
-------------------------
localhost 7676
Name Client ID Number of Durable Sub
Messages State
----------------------------------------------------------------
myDurable myClientID 1 INACTIVE
Successfully listed durable subscriptions.
可以使用 list 命令返回的信息标识希望销毁或清理其消息的长期订阅。使用订阅名称和客户机 ID 可以标识订阅。例如：
imqcmd destroy dur -n myDurable -c myClientID
管理事务
客户机应用程序启动的所有事务都由代理进行跟踪。这些事务可以是 XA 资源管理器管理的简单 MQ 事务或分布式事务（请参阅本地事务）。所有事务都有一个 MQ 事务 ID，这是一个 64 位的数字，唯一标识代理上的每个事务。分布式事务也有一个分布式事务 ID (XID)，长度为 128 字节，由分布式事务管理器指定。MQ 负责维护 MQ 事务 ID 与 XID 之间的关联。
对于分布式事务来说，失败的事务可能会保持 PREPARED 状态，而不会提交。因此，管理员需要监视并在需要时回滚或提交那些处于 PREPARED 状态的事务。
表 6-12 概述了 imqcmd 事务子命令。如果不使用默认代理 (localhost:7676)，则必须指定主机名和端口。
表 6-12 用于管理事务的 imqcmd 子命令
子命令
说明
list txn
列出代理跟踪的所有事务。
query txn -n transaction_id
列出指定事务的相关信息。
commit txn -n transaction_id
提交指定的事务。
rollback txn -n transaction_id
回滚指定的事务。
例如，以下命令将列出某个代理中的所有事务。
imqcmd list txn
对于每个事务，list 子命令将返回事务 ID、状态、用户名、消息或确认的数量以及创建时间。例如：
Listing all the transactions on the broker specified by:
-------------------------
Host Primary Port
-------------------------
localhost 7676
---------------------------------------------------------------
Transaction ID State User name # Msgs/ Creation time
# Acks
---------------------------------------------------------------
64248349708800 PREPARED guest 4/0 1/30/02 10:08:31 AM
64248371287808 PREPARED guest 0/4 1/30/02 10:09:55 AM
Successfully listed transactions.
该命令显示了代理中的所有事务，包括本地事务和分布式事务。只能提交或回滚处于 PREPARED 状态的事务。只有当您知道该事务由于失败而处于 PREPARED 状态，而且分布式事务管理器当前没有提交该事务时才可以这样做。
例如，如果代理的 auto-rollback 属性被设置为 false（请参阅表 2-4），那么必须在启动代理时手动提交或回滚发现处于 PREPARED 状态的事务。
list 子命令还显示事务中生成和确认的消息数量 (#Msgs/#Acks)。提交事务之前不会传送消息，也不会处理确认。
query 子命令也可以显示这些信息，除此之外，它还显示以下信息：客户机 ID、连接标识和分布式事务 ID (XID)。例如：
imqcmd query txn -n 64248349708800
此语句的输出如下：
Querying the transaction where:
-------------------------
Transaction ID
-------------------------
64248349708800
On the broker specified by:
-------------------------
Host Primary Port
-------------------------
localhost 7676
Client ID
Connection guest@192.18.116.219:62209->jms:62195
Creation time 1/30/02 10:08:31 AM
Number of acknowledgements 0
Number of messages 4
State PREPARED
Transaction ID 64248349708800
User name guest
XID
6469706F6C7369646577696E6465723130313234313431313030373230
Successfully queried the transaction.
commit 和 rollback 子命令可用于提交和回滚分布式事务。正如前文所述，只能提交或回滚处于 PREPARED 状态的事务。例如：
imqcmd commit txn -n 64248349708800
您也可以配置代理，使它在启动时自动回滚处于 PREPARED 状态的事务。有关详细信息，请参阅表 2-4 中的 imq.transaction.autorollback 属性。