第 5 章 管理代理
本章介绍如何使用 imqcmd 实用程序来管理代理及其服务。本章包括以下各节：
本章并未涵盖与管理代理相关的全部主题。其他主题将在后面的各章中进行介绍：
-
管理代理上的物理目的地。有关如何创建、显示、更新和销毁物理目的地，以及如何使用停用消息队列等主题的信息，请参见第 6 章，管理物理目的地。
-
设置代理的安全性。有关用户验证、访问控制、加密、密码文件和审计日志等主题的信息，请参见第 7 章，管理安全性。
前提条件
使用 imqcmd 和 imqusermgr 命令行实用程序来管理代理。 在管理代理前，必须执行以下操作：
-
使用 imqbrokerd 实用程序命令启动代理。在代理运行前，不能使用其他命令行实用程序。
-
确定要设置 Message QueueTM 管理用户，还是使用默认帐户。要使用管理命令，必须指定用户名和密码。
安装 Message Queue 时，会安装默认的用户系统信息库，这是一个平面文件。该系统信息库包含两个默认条目：admin 用户和 guest 用户。如果要测试 Message Queue，可以使用默认用户名和密码 (admin/ admin) 来运行 imqcmd 实用程序。
如果要设置生产系统，则必须为管理用户设置验证和授权。有关设置基于文件的用户系统信息库或配置 LDAP 目录服务器的使用的信息，请参见第 7 章，管理安全性。在生产环境中，使用非默认用户名和密码是一种比较安全的做法。
-
如果要使用安全的代理连接，请在目标代理实例中设置并启用 ssladmin 服务。有关详细信息，请参见消息加密。
使用 imqcmd 实用程序
imqcmd 实用程序用于管理代理及其服务。
有关 imqcmd 命令的语法、子命令和选项的参考信息，请参见第 13 章，命令行参考。在单独的第 15 章，物理目的地属性参考中，介绍了管理物理目的地时可使用的参考信息。
显示帮助
要显示有关 imqcmd 实用程序的帮助，请使用 -h 或 -H 选项，而不要使用子命令。您无法获取有关特定子命令的帮助。
例如，以下命令显示有关 imqcmd 的帮助：
imqcmd -H
如果输入的命令行除了包含 -h 或 -H 选项外，还包含子命令或其他选项，则 imqcmd 实用程序只处理 -h 或 -H 选项。命令行中的其他所有项均被忽略。
显示产品版本
要显示 Message Queue 产品版本，请使用 -v 选项。例如：
imqcmd -v
如果输入的命令行除了包含 -v 选项外，还包含子命令或其他选项，则 imqcmd 实用程序只处理 -v 选项。命令行中的其他所有项均被忽略。
指定用户名和密码
因为将对照用户系统信息库验证每个 imqcmd 子命令，所以每个子命令都要求提供用户名和密码。唯一的例外是使用 -h 或 -H 选项来显示帮助的命令以及使用 -v 选项来显示产品版本的命令。
指定用户名
使用 -u 选项可指定管理用户名。如果省略了用户名，该命令会提示您输入它。例如，以下命令显示有关默认代理的信息：
imqcmd query bkr -u admin
为使本章中的示例便于阅读，我们将默认用户名 admin 显示为 -u 选项的参数。在生产环境中，应该使用自定义的用户名。
指定密码
使用以下方法之一指定密码：
-
创建密码文件 (passfile) 并在该文件中输入密码。在命令行中，使用 -passfile 选项提供密码文件的名称。
-
让命令提示您输入密码。
在 Message Queue 的以前版本中，可以使用 -p 选项在 imqcmd 命令行中指定密码。不赞成使用此选项，在今后的版本中会将其删除。
指定代理名和端口
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 服务（如果已配置并启动了该服务）。
显示代理信息
要查询并显示某个代理的信息，请使用 query bkr 子命令。
下面是 query bkr 子命令的语法：
imqcmd query bkr -b hostName: portNumber
该子命令列出默认代理或指定主机和端口上的代理的当前属性设置。它还列出与指定代理连接且正在运行的代理（在多代理群集中）。
imqcmd query bkr -u admin
提示输入密码后，此命令将产生类似如下内容的输出：
Version 3.6
Instance Name imqbroker
Primary Port 7676
Current Number of Messages in System 0
Current Total Message Bytes in System 0
Current Number of Messages in Dead Message Queue 0
Current Total Message Bytes in Dead Message Queue 0
Log Dead Messages true
Truncate Message Body in Dead Message Queue false
Max Number of Messages in System unlimited (-1)
Max Total Message Bytes in System unlimited (-1)
Max Message Size 70m
Auto Create Queues true
Auto Create Topics true
Auto Created Queue Max Number of Active Consumers 1
Auto Created Queue Max Number of Backup Consumers 0
Cluster Broker List (active)
Cluster Broker List (configured)
Cluster Master Broker
Cluster URL
Log Level INFO
Log Rollover Interval (seconds) 604800
Log Rollover Size (bytes) unlimited (-1)
|
更新代理属性
可以使用 update bkr 子命令更新以下代理属性：
下面是 update bkr 子命令的语法：
imqcmd update bkr [-b hostName: portNumb er]-o attribute=value [[-o attribute=value1] …]
该子命令更改默认代理或指定主机和端口上的代理的指定属性。例如，以下命令禁止自动创建队列目的地：
imqcmd update bkr -o "imq.autocreate.queue=false" -u admin
这些属性在第 14 章，代理属性参考中介绍。
暂停和恢复代理
启动代理后，可以使用 imqcmd 子命令控制代理的状态。
暂停代理
暂停代理时暂停的是代理的连接服务线程，从而使代理停止侦听连接端口。其结果是代理将无法再接受新连接、接收消息或分发消息。
但是，暂停代理不会暂停 admin 连接服务，因此您可以执行相应的管理任务，以控制发送到代理的消息流。暂停代理也不会暂停 cluster 连接服务。但是，群集中的消息传送依赖于群集中的不同代理所执行的传送功能。因此，暂停群集中的代理可能导致某些消息流的速度变慢。
下面是 pause bkr 子命令的语法：
imqcmd pause bkr [-b hostName: portNumber]
以下命令暂停在 myhost 端口 1588 上运行的代理。
imqcmd pause bkr -b myhost:1588 -u admin
也可以暂停单个连接服务和单个物理目的地。有关详细信息，请参见暂停和恢复连接服务和暂停和恢复物理目的地。
恢复代理
恢复代理将重新激活代理的服务线程，使代理恢复侦听端口。
下面是 resume bkr 子命令的语法：
imqcmd resume bkr [-b hostName: portNumber]
以下命令将恢复在 localhost 端口 7676 上运行的代理。
imqcmd resume bkr -u admin
关闭并重新启动代理
关闭代理将正常终止代理进程。代理将停止接受新的连接和消息，并在完成现有消息的传送后终止代理进程。
下面是 shutdown bkr 子命令的语法：
imqcmd shutdown bkr [-b hostName: portNumber]
以下命令将关闭在 ctrlsrv 端口 1572 上运行的代理：
imqcmd shutdown bkr -b ctrlsrv:1572 -u admin
使用 restart bkr 子命令可关闭并重新启动代理。下面是 restart bkr 子命令的语法：
imqcmd restart bkr [-b hostName: portNumber]
该子命令关闭并重新启动默认代理或指定主机和端口上的代理，重新启动时使用首次启动代理时指定的选项。 要选择其他选项，请关闭代理，然后通过指定所需的选项来重新启动它。
显示代理度量
要显示有关代理的度量信息，请使用 metrics bkr 子命令。
下面是 metrics bkr 子命令的语法：
imqcmd metrics bkr [-b hostName:
portNumber]
[-m metricType] [-int interval] [-msp
numSamples]
此子命令显示默认代理或指定主机和端口上的代理的代理度量。
可以使用 -m 选项来指定显示以下度量类型之一：
-
ttl 显示流入和流出代理的消息和包的度量（默认度量类型）。
-
rts 显示消息和包流入和流出代理的速率的度量（以一秒为衡量单位）。
-
cxn 显示连接、虚拟内存堆和线程。
可以使用 -int 选项来指定显示度量的时间间隔（以秒为单位）。默认值为 5 秒。
可以使用 -msp 选项来指定在输出中显示的样例的数量。默认为无限制（无穷多）。
例如，要获得消息在 10 秒间隔内流入和流出代理的速率，请使用以下命令：
imqcmd metrics bkr -m rts -int 10 -u admin
此命令产生的输出如下：
-------------------------------------------------------- Msgs/sec Msg Bytes/sec Pkts/sec Pkt Bytes/sec In Out In Out In Out In Out -------------------------------------------------------- 0 0 27 56 0 0 38 66 10 0 7365 56 10 10 7457 1132 0 0 27 56 0 0 38 73 0 10 27 7402 10 20 1400 8459 0 0 27 56 0 0 38 73 |
有关代理所收集的和报告的数据的更详细描述，请参见代理范围内的度量。
管理连接服务
imqcmd 实用程序包含可用于执行以下连接服务管理任务的子命令：
代理既支持来自应用程序客户端的连接 ，也支持来自管理客户端的连接。表 5–1 显示了 Message Queue 代理中当前可用的连接服务。 如该表所示，每项服务都与它所使用的服务类型（对于应用程序客户端是 NORMAL ，对于管理客户端是 ADMIN）和底层传输协议关联。
表 5–1 Message Queue 连接服务|
服务名称 |
服务类型 | |
|---|---|---|
|
NORMAL | ||
|
NORMAL | ||
|
NORMAL | ||
|
NORMAL | ||
|
ADMIN |
TCP |
|
|
ADMIN |
TLS（基于 SSL 的安全性） |
您可以使用 imqcmd 子命令将连接服务作为一个整体进行管理，也可以管理某项特定的连接服务。如果子命令的目标是某项特定的服务，请使用 -n 选项指定表 5–1 的“服务名称”列中列出的某个名称。
列出连接服务
要列出代理中可用的连接服务，请使用 list svc 子命令。
下面是 list svc 子命令的语法：
imqcmd list svc [-b hostName: portNumber]
此子命令列出默认代理或指定主机和端口上的代理中的所有连接服务。
以下命令列出在 localhost 端口 7676 上运行的代理中的所有服务：
imqcmd list svc -u admin
该命令将输出如下信息：
------------------------------------------------ Service Name Port Number Service State ------------------------------------------------ admin 41844 (dynamic) RUNNING httpjms - UNKNOWN httpsjms - UNKNOWN jms 41843 (dynamic) RUNNING ssladmin dynamic UNKNOWN ssljms dynamic UNKNOWN |
显示连接服务信息
要查询并显示某项服务的信息，请使用 query 子命令。
下面是 query svc 子命令的语法：
imqcmd query svc -n serviceName [-b hostName:portNumber]
query svc 子命令显示在默认代理或指定主机和端口上的代理中运行的指定服务的相关信息。
例如：
imqcmd query svc -n jms -u admin
提示输入密码后，此命令将产生类似如下内容的输出：
Service Name jms
Service State RUNNING
Port Number 60920 (dynamic)
Current Number of Allocated Threads 0
Current Number of Connections 0
Min Number of Threads 10
Max Number of Threads 1000
|
更新连接服务属性
可以使用 update 子命令更改表 5–2 中列出的一个或多个服务属性的值。
表 5–2 imqcmd 更新的连接服务属性|
属性 |
描述 |
|---|---|
|
port |
为要更新的服务指定的端口（不适用于 httpjms 或 httpsjms）。值为 0 表示端口由端口映射器动态分配。 |
|
minThreads | |
|
maxThreads |
最多可分配给服务的线程数。 |
下面是 update 子命令的语法：
imqcmd update svc -n serviceName [-b
hostName:portNumber]
-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:portNumber] [-m metricType
]
[-int interval] [-msp numSamples]
此子命令显示默认代理或指定主机和端口上的代理中指定服务的度量。
使用 -m 选项指定要显示的度量类型：
-
ttl 显示有关通过指定的连接服务流入和流出代理的消息和包的度量。（默认度量类型。）
-
rts 显示有关消息和包通过指定的连接服务流入和流出代理的速率的度量（以一秒为衡量单位）。
-
cxn 显示连接、虚拟内存堆和线程。
可以使用 -int 选项来指定显示度量的时间间隔（以秒为单位）。默认值为 5 秒。
可以使用 -msp 选项来指定在输出中显示的样例的数量。默认为无限制（无穷多）。
例如，要获得 jms 连接服务处理的消息和包的累计总数，请使用以下命令：
imqcmd metrics svc -n jms -m ttl -u admin
------------------------------------------------- Msgs Msg Bytes Pkts Pkt Bytes In Out In Out In Out In Out ------------------------------------------------- 164 100 120704 73600 282 383 135967 102127 657 100 483552 73600 775 876 498815 149948 |
有关使用 imqcmd 来报告连接服务度量的详细说明，请参见连接服务度量。
暂停和恢复连接服务
要暂停除管理服务之外的其他任何服务（不能暂停管理服务），请使用 pause svc 和 resume svc 子命令。
下面是 pause svc 子命令的语法：
imqcmd pause svc -n serviceName [-b hostName:portNumber]
此子命令暂停在默认代理或指定主机和端口上的代理中运行的指定服务。例如，以下命令暂停在默认代理上运行的 httpjms 服务。
imqcmd pause svc -n httpjms -u admin
暂停服务有如下影响：
-
代理将停止在已暂停的服务上接受新的客户端连接。如果 Message Queue 客户端尝试打开新的连接，将出现异常。
-
已暂停的服务上的所有现有连接都将保持活动状态，但是代理将暂停这些连接上的所有消息处理，直到服务恢复。（例如，在服务恢复之前，将禁止客户端尝试使用 send 方法来发送消息。）
-
代理已接收的任何消息的消息传送状态都将保留。（例如，事务不会中断，消息传送将在服务恢复之后恢复。）
要恢复服务，请使用 resume svc 子命令。
下面是 resume svc 子命令的语法：
imqcmd resume svc -n serviceName[-b hostName:portNumber]
此子命令恢复在默认代理或指定主机和端口上的代理中运行的指定服务。
获取有关连接的信息
imqcmd 实用程序包含可用来列出并获取连接信息的子命令。
list cxn 子命令列出指定服务名的全部连接。下面是 list cxn 子命令的语法：
imqcmd list cxn [-svn serviceName] [-b hostName:portNumber]
此子命令列出默认代理或指定主机和端口上的代理中指定服务名的所有连接。 如果未指定服务名，将列出所有连接。
例如，以下命令列出默认代理上的所有连接：
imqcmd list cxn -u admin
提示输入密码后，此命令将产生类似如下内容的输出：
Listing all the connections on the broker specified by: ----------------------------------- Host Primary Port ------------------------------------ localhost 7676 --------------------------------------------------------------------------- Connection ID User Service Producers Consumers Host --------------------------------------------------------------------------- 1964412264455443200 guest jms 0 1 127.0.0.1 1964412264493829311 admin admin 1 1 127.0.0.1 Successfully listed connections. |
要查询并显示某项连接服务的信息，请使用 query 子命令。
query cxn -n connectionID [-b hostName:portNumber]
此子命令显示默认代理或指定主机和端口上的代理中的指定连接的信息。
imqcmd query cxn -n 421085509902214374 -u admin
提示输入密码后，此命令将产生类似如下内容的输出：
Connection ID 421085509902214374 User guest Service jms Producers 0 Consumers 1 Host 111.22.333.444 Port 60953 Client ID Client Platform |
管理长期订阅
使用 imqcmd 子命令，可以通过执行下面一项或多项操作来管理代理的长期订阅：
-
列出长期订阅
-
清除长期订阅的所有消息
-
销毁长期订阅
长期订阅是指客户端注册为长期项的主题订阅；长期订阅有唯一标识，它要求代理保留该订阅的消息，即使订阅使用方变为非活动状态也是如此。 通常情况下，代理只能在消息已过期的情况下删除为长期订户保留的消息。
要列出指定物理目的地的长期订阅，请使用 list dur 子命令。下面是 list dur 子命令的语法：
imqcmd list dur -d destName
例如，以下命令使用本地主机的默认端口上的代理，列出 SPQuotes 主题的所有长期订阅：
imqcmd list dur -d SPQuotes
对于主题的每个长期订阅，list dur 子命令都返回长期订阅的名称、用户的客户端 ID、排队发往该主题的消息数量以及长期订阅的状态（活动/非活动）。例如：
Name Client ID Number of Durable Sub
Messages State
----------------------------------------------------------------
myDurable myClientID 1 INACTIVE
|
可以使用 list dur 子命令返回的信息标识您要销毁或要清除其消息的长期订阅。
purge dur 子命令清除带有指定客户端标识符的指定长期订阅的所有消息。下面是 purge dur 子命令的语法：
imqcmd purge dur -n subscrName -c clientID
destroy dur 子命令销毁带有指定客户端标识符的指定长期订阅。下面是 destroy dur 子命令的语法：
imqcmd destroy dur -n subscrName -c clientID
例如，以下命令销毁长期订阅 myDurable 和客户端 ID myClientID。
imqcmd destroy dur -n myDurable -c myClientID
管理事务
客户端应用程序启动的所有事务都由代理来跟踪。这些事务可以是简单 Message Queue 事务，也可以是分布式事务（XA 资源）管理器管理的分布式事务。
每个事务都有一个 Message Queue 事务 ID：这是一个 64 位数字，用于唯一标识代理上的事务。分布式事务也有一个分布式事务 ID (XID)，长度可达 128 字节，由分布式事务管理器指定。Message Queue 负责维护 Message Queue 事务 ID 与 XID 之间的关联。
对于分布式事务而言，当失败时，事务可能停留在 PREPARED 状态，而不会提交。因此，作为管理员，您需要监视事务的状态，并回滚或提交那些停留在 PREPARED 状态的事务。
要列出代理跟踪的所有事务，请使用 list txn 命令。下面是 list txn 子命令的语法：
imqcmd list txn
例如，以下命令列出某个代理中的所有事务。
imqcmd list txn
对于每个事务，list 子命令将返回事务 ID、状态、用户名、消息数或确认数以及创建时间。例如：
---------------------------------------------------------------
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
|
该命令显示了代理中的所有事务，包括本地事务和分布式事务。只能提交或回滚处于 PREPARED 状态的事务。只有当您知道该事务由于失败而停留在 PREPARED 状态，而且分布式事务管理器当前没有提交该事务时才可以这样做。
例如，如果代理的 auto-rollback 属性设置为 false（请参见表 14–2），则必须在代理启动时手动提交或回滚处于 PREPARED 状态的事务。
list 子命令还分别显示事务中生成和确认的消息数 (#Msgs/#Acks)。提交事务之前不会传送这些消息，也不会处理确认。
query 子命令可以显示上述信息以及其他许多值：客户端 ID、连接标识和分布式事务 ID (XID)。下面是 query txn 子命令的语法：
imqcmd query txn -n transactionID
例如，以下示例生成如下所示的输出：
imqcmd query txn -n 64248349708800
Client ID Connection guest@192.18.116.219:62209->jms:62195 Creation time 1/30/02 10:08:31 AM Number of acknowledgments 0 Number of messages 4 State PREPARED Transaction ID 64248349708800 User name guest XID 6469706F6C7369646577696E6465723130313234313431313030373230 |
使用 commit 和 rollback 子命令可以提交和回滚分布式事务。正如前文所述，只能提交和回滚处于 PREPARED 状态的事务。
下面是 commit 子命令的语法：
imqcmd commit txn -n transactionID
例如：
imqcmd commit txn -n 64248349708800
imqcmd rollback txn -n transactionID
有关详细信息，请参见表 14–2 中的 imq.transaction.autorollback 属性。
也可以配置代理，使它在启动时自动回滚处于 PREPARED 状态的事务。
- © 2010, Oracle Corporation and/or its affiliates