第 5 章 管理代理
第 5 章
管理代理
本章介绍如何执行与管理代理及其服务相关的基本任务。本章包含以下小节：
本章并未涵盖与管理代理相关的全部主题。其他较大的主题将在后面的单独章节中进行介绍：
- 管理代理上的物理目标。有关如何创建、显示、更新和销毁物理目标，以及如何使用停用消息队列等主题的信息，请参见第 6 章“管理物理目标”。
- 设置代理的安全性。有关用户验证、访问控制、加密、密码文件和审计日志等主题的信息，请参见第 7 章“管理安全性”。
前提条件
使用 imqcmd 和 imqusermgr 命令来管理代理。在管理代理前，必须执行以下操作：
- 使用 imqbrokerd 命令启动代理。在代理运行前，不能使用其他命令。
- 确定要设置 Message Queue 管理用户，还是使用默认帐户。要使用管理命令，必须指定用户名和密码。
安装 Message Queue 时，系统会安装默认的用户系统信息库，这是一个平面文件。系统信息库发行时包括两个默认条目：管理员用户和 guest 用户。如果要测试 Message Queue，可使用默认用户名和密码 (admin/admin) 运行 imqcmd 实用程序。
如果要设置生产系统，则必须为管理用户设置验证和授权。有关设置基于文件的用户系统信息库或配置 LDAP 目录服务器的使用的信息，请参见第 7 章“管理安全性”。在生产环境中，使用非默认用户名和密码是一项比较安全的做法。
- 如果要使用安全的代理连接，请在目标代理实例中设置并启用 ssladmin 服务。有关详细信息，请参见使用基于 SSL 的服务。
使用 imqcmd 命令实用程序
imqcmd 命令实用程序可用于管理代理及其服务。
有关 imqcmd 命令的语法、子命令和选项的参考信息，请参见第 13 章“命令参考”。在单独章节第 15 章“物理目标属性参考”中，介绍了管理物理目标时使用的参考信息。
指定用户名和密码
因为每个 imqcmd 命令均通过用户系统信息库进行验证，因此要求提供用户名和密码。唯一的特例如下：
- 使用 -h 或 -H 选项显示帮助命令的命令。
- 使用 -v 选项显示产品版本的命令。
指定用户名
使用 -u 选项指定管理用户名。如果省略了用户名，该命令会提示您输入用户名。
为使本章中的示例便于阅读，我们将默认用户名 admin 显示为 -u 选项的参数。在生产环境中，应该使用自定义的用户名。
指定密码
按以下方法之一指定密码：
- 创建密码文件 (passfile) 并在该文件中输入密码。在命令行中，使用 -passfile 选项提供密码文件的名称。
- 让命令提示您输入密码。这种指定密码的方法最安全，除非有人看见了输入的内容。
在 Message Queue 以前的版本中，可以使用 -p 选项在命令行中指定密码。不赞成使用此选项，在今后的版本中会将其删除。
指定代理名和端口
imqcmd 的默认代理是本地主机上运行的代理，默认端口是 7676。
如果对远程主机和/或非默认端口上运行的代理执行命令，必须使用 -b 选项指定代理的主机和端口。
示例
本节中的示例说明了 imqcmd 的用法。
第一个示例列出了在 localhost 7676 端口上运行的代理的属性，因此不需要使用 -b 选项。该命令使用默认管理用户名 (admin) 并省略了密码，因此命令会提示您输入密码。
imqcmd query bkr -u admin
以下示例将列出在 myserver 1564 端口上运行的代理的属性。用户名是 aladdin。该命令要求更新用户系统信息库，以便将用户名 aladdin 分配给 admin 组。
imqcmd query bkr -b myserver:1564 -u aladdin
以下示例将列出在 localhost 7676 端口上运行的代理的属性。命令的初始超时设置为 20 秒，超时后的重试次数设置为 7。用户密码在名为 myPassfile 的密码文件中，该文件位于调用命令时的当前目录中。
imqcmd query bkr -u admin -passfile myPassfile -rtm 20 -rtr 7
对于安全的代理连接，这些示例可能会包括 -secure 选项。-secure 选项使 imqcmd 使用 ssladmin 服务（如果已配置并启动了该服务）。
显示帮助
要显示有关 imqcmd 命令实用程序的帮助，请使用 -h 或 -H 选项，而不要使用子命令。您无法获取有关特定子命令的帮助。
例如，以下命令显示有关 imqcmd 的帮助：
imqcmd -H
如果输入的命令行除了包括子命令或其他选项外，还包括 -h 或 -H 选项，则该命令实用程序只处理 -h 或 -H 选项。命令行中的所有其他项均被忽略。
显示产品版本
要显示 Message Queue 产品版本，请使用 -v 选项。例如：
imqcmd -v
如果输入的命令行除了包括子命令或其他选项外，还包括 -v 选项，则该命令实用程序只处理 -v 选项。命令行中的所有其他项均被忽略。
显示代理信息
要查询并显示某个代理的信息，请使用 query bkr 子命令。
下面是 query bkr 子命令的语法：
imqcmd query bkr -b hostName:port
该子命令列出默认代理或指定主机和端口上的代理的当前属性设置。它还列出与指定代理连接且正在运行的代理（在多代理群集中）。
例如：
imqcmd query bkr -u admin
提示输入密码后，此命令将产生类似如下内容的输出：
|
更新代理属性
可以使用 update bkr 子命令更新以下代理属性：
- imq.autocreate.queue
- imq.autocreate.topic
- imq.autocreate.queue.maxNumActiveConsumers
- imq.autocreate.queue.maxNumBackupConsumers
- imq.cluster.url
- imq.destination.DMQ.truncateBody
- imq.destination.logDeadMsgs
- imq.log.level
- imq.log.file.rolloversecs
- imq.log.file.rolloverbytes
- imq.system.max_count
- imq.system.max_size
- imq.message.max_size
- imq.portmapper.port
下面是 update bkr 子命令的语法：
imqcmd update bkr [-b hostName:port]-o attribute=value [-o attribute=value1]…
此子命令更改默认代理或指定主机和端口的代理的指定属性。
第 14 章“代理属性参考” 中介绍了这些属性。
例如，以下命令可关闭队列目标的自动创建：
imqcmd update bkr -o “imq.autocreate.queue=false” -u admin
暂停和恢复代理
启动代理后，可以使用 imqcmd 子命令控制其状态。
暂停代理
暂停代理将暂停代理的连接服务线程，从而使代理停止侦听连接端口。其结果是代理将无法接受新连接、接收消息、发送消息。
但是，暂停代理不会暂停 admin 连接服务，允许执行控制代理消息流所需的管理任务。例如，如果某个特殊的物理目标受到消息攻击，您就可以暂停该代理，然后执行下列操作以期解决该问题：
- 跟踪消息来源
- 限制物理目标的大小
- 销毁物理目标
暂停代理也不会暂停 cluster 连接服务。但是，群集中的消息传送依赖于群集中不同代理所执行的传送功能。
下面是 pause bkr 子命令的语法：
imqcmd pause bkr [-b hostName:port]
此命令暂停默认代理或指定主机和端口的代理。
以下命令暂停在 myhost 1588 端口上运行的代理。
imqcmd pause bkr -b myhost:1588 -u admin
也可以暂停单个连接服务和单个物理目标。有关详细信息，请参见暂停和恢复连接服务和暂停和恢复物理目标。
恢复代理
恢复代理将重新激活代理的服务线程，使代理恢复侦听端口。
下面是 resume bkr 子命令的语法：
imqcmd resume bkr [-b hostName:port]
此子命令恢复默认代理或指定主机和端口的代理。
以下命令将恢复在 localhost 7676 端口上运行的代理。
imqcmd resume bkr -u admin
关闭并重新启动代理
关闭代理将正常终止代理进程。代理停止接收新的连接和消息，完成现有消息的传送后将终止代理进程。
下面是 shutdown bkr 子命令的语法：
imqcmd shutdown bkr [-b hostName:port]
此子命令关闭默认代理或指定主机和端口的代理。
以下命令将关闭在 ctrlsrv 1572 端口上运行的代理：
imqcmd shutdown bkr -b ctrlsrv:1572 -u admin
您可以关闭并重新启动代理。下面是 restart bkr 子命令的语法：
imqcmd restart bkr [-b hostName:port]
该子命令关闭并重新启动默认代理或指定主机和端口的代理，（使用首次启动该代理时指定的选项）要选择其他选项，请关闭并重新启动该代理以指定所需的选项。
以下命令将重新启动在 localhost 7676 端口上运行的代理：
imqcmd restart bkr -u admin
显示代理度量
要显示有关代理的度量信息，请使用 metrics bkr 子命令。
下面是 metrics bkr 子命令的语法：
imqcmd metrics bkr [-b hostName:port]
[-m metricType] [-int interval] [-msp numSamples]
此子命令显示默认代理或指定主机和端口的代理的代理度量。
可以使用 -m 选项指定要显示的以下度量类型之一：
- ttl 显示流入和流出代理的消息和包的度量（默认度量类型）。
- rts 显示消息和包流入和流出代理的速率（每秒）的度量。
- cxn 显示连接、虚拟内存堆和线程。
使用 -int 选项指定显示度量的时间间隔（以秒为单位）。默认值为 5 秒。
使用 -msp 选项指定在输出中显示的样例数量。默认值为无限数（无穷大）。
例如，要获得消息在 10 秒间隔内流入和流出代理的速率，请使用以下命令：
imqcmd metrics bkr -m rts -int 10 -u admin
此命令语句的输出如下：
|
有关使用 imqcmd 报告代理度量的详细说明，请参见代理范围度量。
管理连接服务
命令行实用程序包含的子命令可用于执行以下连接服务管理任务：
代理支持与应用程序客户机和管理客户机的连接。表 5-1 显示了 Message Queue 代理当前可用的连接服务。“服务名称”一栏中的值用于为 -n 选项指定服务名称。如该表所示，每项服务都与它所使用的服务类型 NORMAL（用于应用程序客户机）或 ADMIN（用于管理客户机）和底层传输协议相关联。
|
服务名称 |
服务类型 |
协议类型 |
|---|---|---|
|
jms |
NORMAL |
tcp |
|
ssljms（企业版） |
NORMAL |
tls（其安全性基于 SSL） |
|
httpjms（企业版） |
NORMAL |
http |
|
httpsjms（企业版） |
NORMAL |
https（其安全性基于 SSL） |
|
admin |
ADMIN |
tcp |
|
ssladmin（企业版） |
ADMIN |
tls（其安全性基于 SSL） |
列出连接服务
要列出代理中可用的连接服务，请使用 list svc 子命令。
下面是 list svc 子命令的语法：
imqcmd list svc [-b hostName:port]
此子命令列出默认代理或指定主机和端口的代理中的所有连接服务。
在命令行中使用该子命令，如下所示：
imqcmd list svc [-b hostName:portNumber] -u admin
例如，以下命令列出在主机 myServer（位于 6565 端口）上运行的代理所支持的服务。
imqcmd list svc -b MyServer:6565 -u admin
以下命令列出在 localhost 7676 端口上运行的代理上的所有服务：
imqcmd list svc -u admin
该命令的输出信息如下：
|
显示连接服务信息
要查询并显示某项服务的信息，请使用 query 子命令。
下面是 query svc 子命令的语法：
imqcmd query svc -n serviceName [-b hostName:port]
有关在默认代理或指定主机和端口上运行的代理的指定服务的子命令信息。
例如：
imqcmd query svc -n jms -u admin
提示输入密码后，此命令将产生类似如下内容的输出：
|
更新连接服务属性
可以使用 update 子命令更改表 5-2 中列出的一个或多个服务属性的值。
|
属性 |
说明 |
|---|---|
|
port |
为要更新的服务指定的端口（不适用于 httpjms 和 httpsjms）。0 值表示端口由端口映射器动态分配。 |
|
minThreads |
为服务指定的最小线程数。 |
|
maxThreads |
为服务指定的最大线程数。 |
下面是 update 子命令的语法：
imqcmd update svc -n serviceName [-b hostName:port]
-o attribute=value [-o attribute=value1]…
此子命令更新在默认代理或指定主机和端口上运行的代理中的指定服务的指定属性。有关服务属性的说明，请参见连接服务属性。
以下命令将指定给 jms 服务的最小线程数更改为 20。
imqcmd update svc -n jms -o "minThreads=20" -u admin
显示连接服务度量
要显示有关某个服务的度量信息，请使用 metrics 子命令。
下面是 metrics 子命令的语法：
imqcmd metrics svc -n serviceName [-b hostName:port] [-m metricType]
[-int interval] [-msp numSamples]
此子命令显示默认代理或指定主机和端口上的代理中指定服务的度量。
使用 -m 选项指定要显示的度量类型：
- ttl 显示消息和包按指定连接服务方式流入和流出代理的度量。（默认度量类型）
- rts 显示消息和包按指定连接服务方式流入和流出代理的速率（每秒）度量。
- cxn 显示连接、虚拟内存堆和线程。
使用 -int 选项指定显示度量的时间间隔（以秒为单位）。默认值为 5 秒。
使用 -msp 选项指定在输出中显示的样例数量。默认值为无限数（无穷大）。
例如，要获得 jms 连接服务处理的消息和包的累计总数，请使用以下命令：
imqcmd metrics svc -n jms -m ttl -u admin
提示输入密码后，此命令将产生类似如下内容的输出：
|
有关使用 imqcmd 报告连接服务度量的详细说明，请参见连接服务度量。
暂停和恢复连接服务
要暂停除管理服务之外的任何其他服务（不能暂停管理服务），请使用 pause svc 和 resume svc 子命令。
下面是 pause svc 子命令的语法：
imqcmd pause svc -n serviceName [-b hostName:port]
此子命令暂停在默认代理或指定主机和端口上运行的代理中的指定服务。不能暂停管理服务。
使用如下所示的命令行：
imqcmd pause svc -n serviceName -u admin
暂停服务影响如下：
- 代理将停止接受暂停服务的新客户机连接。如果 Message Queue 客户机尝试打开新的连接，将出现异常。
- 暂停服务的所有现有连接将保持活动状态，但是代理将暂停这些连接上的所有消息处理，直到服务恢复。（例如，如果客户机尝试发送消息，将禁止使用 send() 方法，直到服务恢复。）
- 会保留代理已经接收的任何消息的消息传送状态。（例如，服务恢复之后，事务不会中断，消息传送将恢复。）
要恢复服务，请使用 resume svc 子命令。
下面是 resume svc 子命令的语法：
imqcmd resume svc -n serviceName[-b hostName:port]
此子命令恢复在默认代理或指定主机和端口上运行的代理中的指定服务。
使用如下所示的命令行：
imqcmd resume svc -n serviceName -u admin
获得有关连接的信息
命令实用程序包含的子命令允许您列出并获得有关连接的信息。
list cxn 子命令列出指定服务名称的全部连接。下面是 list cxn 子命令的语法：
imqcmd list cxn [-svn serviceName] [-b hostName:port]
此子命令列出默认代理或指定主机和端口上的代理中指定服务名称的所有连接。如果未指定服务名称，将列出所有连接。
例如：
imqcmd list cxn -u admin
提示输入密码后，此命令将产生类似如下内容的输出：
|
要查询并显示某项连接服务的信息，请使用 query 子命令。
query cxn -n connectionID [-b hostName:port]
此子命令显示默认代理或指定主机和端口上的代理中的指定连接的信息。
例如：
imqcmd query cxn -n 421085509902214374 -u admin
提示输入密码后，此命令将产生类似如下内容的输出：
|
管理长期订阅
要管理代理的长期订阅，需要使用 imqcmd 子命令。长期订阅是指某台客户机长期注册订阅某个主题；长期订阅有唯一标识，要求代理保留该订阅的消息，即使消息使用方处于非活动状态。通常，代理只能在消息已过期的情况下删除为长期订户保留的消息。
要列出指定物理目标的长期订阅，请使用 list dur 子命令。下面是 list dur 子命令的语法：
imqcmd list dur -d destName
例如，以下命令使用本地主机默认端口上的代理，列出了 SPQuotes 主题的所有长期订阅：
imqcmd list dur -d SPQuotes
对于某个主题下的每个长期订阅，list dur 子命令将返回长期订阅的名称、用户的客户机 ID、该主题下排队的消息数量以及长期订阅的状态（活动/非活动）。例如：
|
可以使用 list dur 子命令返回的信息标识希望销毁或清除其消息的长期订阅。
destroy dur 子命令销毁带有指定客户机标识符的指定长期订阅。下面是 destroy dur 子命令的语法：
imqcmd destroy dur -n subscrName -c client_id
使用订阅名称和客户机 ID 来标识订阅。例如：
imqcmd destroy dur -n myDurable -c myClientID
purge dur 子命令清除带有指定客户机标识符的指定长期订阅的所有消息。下面是 purge dur 子命令的语法：
imqcmd purge dur -n subscrName -c client_id
管理事务
客户机应用程序启动的所有事务都由代理进行跟踪。这些事务可以是由分布式事务（XA 资源）管理器管理的简单 Message Queue 事务或分布式事务。
每个事务都有一个 Message Queue 事务 ID，这是一个 64 位数字，唯一标识代理上的事务。分布式事务也有一个分布式事务 ID (XID)，长度为 128 字节，由分布式事务管理器指定。Message Queue 负责维护 Message Queue 事务 ID 与 XID 之间的关联。
对于分布式事务来说，失败的事务可能会保持 PREPARED 状态，而不会提交。因此，作为管理员需要监视并回滚或提交那些处于 PREPARED 状态的事务。
要列出代理跟踪的所有事务，请使用 list txn 命令。下面是 list tx 子命令的语法：
imqcmd list txn
例如，以下命令列出某个代理中的所有事务。
imqcmd list txn
对于每个事务，list 子命令将返回事务 ID、状态、用户名、消息或确认数量以及创建时间。例如：
|
该命令显示了代理中的所有事务，包括本地事务和分布式事务。只能提交或回滚处于 PREPARED 状态的事务。只有当您知道该事务由于失败而处于 PREPARED 状态，而且分布式事务管理器当前没有提交该事务时才可以这样做。
例如，如果将代理的 auto-rollback 属性设置为 false（请参见表 14-3），则必须在启动代理时手动提交或回滚处于 PREPARED 状态的事务。
list 子命令还显示事务中生成和确认的消息数量 (#Msgs/#Acks)。提交事务之前不会传送消息，也不会处理确认。
query 子命令可以显示相同的信息以及许多其他值：客户机 ID、连接标识和分布式事务 ID (XID)。下面是 query txn 子命令的语法：
imqcmd query txn -n transaction_id
例如，以下示例生成的输出如下所示：
imqcmd query txn -n 64248349708800
下面是该命令生成的输出：
|
commit 和 rollback 子命令可用于提交和回滚分布式事务。正如前文所述，只能提交或回滚处于 PREPARED 状态的事务。
下面是 commit 子命令的语法：
imqcmd commit txn -n transaction_id
例如：
imqcmd commit txn -n 64248349708800
也可以配置代理，使它在启动时自动回滚处于 PREPARED 状态的事务。
下面是 rollback 子命令的语法：
imqcmd rollback txn -n transaction_id
有关详细信息，请参见表 14-3 中的 imq.transaction.autorollback 属性。
文件号码 819-2219。 版权所有 2005 Sun Microsystems, Inc. 保留所有权利。