|
| Sun ONE Message Queue, Version 3.0.1 管理员指南 |
安装 Sun™ ONE Message Queue (MQ) 以后，可以使用 imqbrokerd 命令来启动代理。代理实例的配置由一组配置文件和使用 imqbrokerd 命令传送的选项共同控制，这些选项会覆盖配置文件中相应的属性。
本章说明了 imqbrokerd 命令的语法，以及如何使用命令行选项和配置文件来配置代理实例。此外，本章还介绍了如何执行以下操作：
- 编辑代理实例配置文件
- 使用代理群集
- 控制代理的日志记录
关于如何启动代理并将其用作 Windows 服务的说明，请参见使用代理作为 Windows 服务。
配置文件
用于配置代理的配置文件将安装在以下目录中。
IMQ_HOME/lib/props/broker
（在 Solaris 操作系统中为 /usr/share/lib/imq/props/broker）该目录存储以下文件：
- 启动时装入的默认配置文件。文件名是 default.properties。该文件不可编辑。您可能需要读取该文件来确定默认设置以及查找要更改的属性的确切名称。
- 安装配置文件，其中包含安装 MQ 时指定的所有属性。文件名是 install.properties。安装完成后该文件不可编辑。
此外，首次运行一个代理时，系统将创建一个实例配置文件，用于指定该代理的实例的配置属性。该文件由代理实例根据管理命令来进行维护，直接编辑该文件时请务必小心。实例配置文件存储在以下位置：
IMQ_VARHOME/instances/brokerName/props/config.properties
（在 Solaris 中为 /var/imq/instances/brokerName/props/config.properties）其中 brokerName 是代理实例的名称（默认值是 imqbroker）。您可以编辑实例配置文件来更改配置（请参见编辑实例配置文件）。
如果连接群集中的代理实例（请参见多代理群集（企业版）），那么可能还需要使用群集配置文件来指定群集配置信息。更多信息，请参见群集配置属性。
合并属性值
启动时，系统会合并不同配置文件中的属性值。它将使用在安装配置文件和实例配置文件中设置的值来覆盖默认配置文件中指定的值。您可以用 imqbrokerd 命令选项来覆盖得到的值。图 5-1 所示为以上说明的图解。
图 5-1 代理配置文件
属性命名语法
配置文件中的所有 MQ 属性定义均使用以下命名语法：
propertyName=value[[,value1]...]
例如，以下项目定义了自动创建队列的队列类型：
imq.queue.default=single
以下项目定义了消息失效期的超时值：
imq.message.expiration.timeout=90
表 5-1 按字母顺序列出了代理配置属性及其默认值。
编辑实例配置文件
首次运行代理实例时，系统将自动创建一个 config.properties 文件。您可以编辑该实例配置文件，以自定义相应代理实例的行为和资源使用。
代理实例仅在启动时读取 config.properties 文件。要持久性更改 config.properties 文件，您可以：
- 使用管理工具。关于可以使用 imqcmd 设置的属性的信息，请参见表 6-5。
- 在代理实例关闭时编辑 config.properties 文件，然后重新启动实例。（在 Solaris 和 Linux 平台中，只有第一个启动代理实例的用户具有编辑 config.properties 文件的权限。）
表 5-1 按字母顺序列出了代理配置属性及其默认值。关于各个属性的含义和用法的更多信息，请参考指定的交叉参考的小节。
启动代理
要启动代理实例，请使用 imqbrokerd 命令。
注 使用管理控制台 (imqadmin) 或命令实用程序 (imqcmd) 无法启动代理实例。这两个 MQ 管理工具只有代理实例已在运行时才能使用。
要覆盖一个或多个属性值，请指定有效的 imqbrokerd 命令行选项。命令行选项覆盖代理配置文件中的值，但仅对当前代理会话有效：命令行选项不会被写入到实例配置文件中。
imqbrokerd 命令的语法如下所示（选项与变量之间以一个空格分隔）：
imqbrokerd [[ -Dproperty=value]...]
[ -backup fileName]
[ -cluster "[broker] [[,broker]...]"
[ -dbuser userName] [ -dbpassword password]
[ -force]
[ -h]
[ -javahome path | -jrehome path]
[ -ldappassword password]
[ -license name]
[ -loglevel level]
[ -metrics number]
[ -name brokerName ] [ -port number]
[ -shared]
[ -password keypassword] [ -passfile fileName]
[ -remove instance]
[ -reset data]
[ -restore fileName]
[ -shared]
[ -silent] [ -tty]
[ -version] [ -vmargs arg [[arg]...]
例如，要启动使用默认代理名称和配置的代理，请使用以下命令：
imqbrokerd
该命令启动一个位于本地计算机上的代理（名为 imqbroker）的默认实例，且其端口映射器的端口号是 7676。
注 在 Solaris 中，可以将代理配置为异常退出后自动重新启动，方法是把 /etc/imq/imqborkerd.conf 配置文件中的 RESTART 属性设置为 YES。
注 在 Solaris 和 Linux 平台中，对包含配置信息和持久性数据的目录的权限取决于第一次启动代理实例的用户的 umask。因此，为了让代理实例正常运行，就只能由原用户启动该实例。
表 5-2 说明了 imqbrokerd 命令的选项以及受到各个选项影响的配置属性（如果存在）。
表 5-2 imqbrokerd 选项
选项
所影响的属性
说明
-backup fileName
不影响任何属性。
仅适用于代理群集。将主管代理的配置更改记录备份到指定的文件。请参见备份主管代理的配置更改记录。
-cluster"[broker]
[[,broker]...]"
broker 可以是将 imq.cluster.brokerlist 设置为要连接的代理的列表。
仅适用于代理群集。连接至指定的主机和端口上的所有代理。该列表将与 imq.cluster.brokerlist 属性中的列表合并。如果没有指定 host 的值，将使用 localhost。如果没有指定 port 的值，将使用值 7676。关于如何使用该选项连接多个代理的更多信息，请参见使用群集（企业版）。
-dbpassword password
将 imq.persist.jdbc.
password 设置为指定密码。指定插入的 JDBC 兼容数据存储的密码。请参见附录 A“设置插入的持久性”。
-dbuser userName
将 imq.persist.jdbc.user
设置为指定用户名。指定插入的 JDBC 兼容数据存储的用户名。请参见附录 A“设置插入的持久性”。
-Dproperty=value
设置系统属性。覆盖实例配置文件中的相关属性值。
将指定属性设置为指定值。关于代理配置属性，请参见表 5-1。
注意：请仔细检查使用 D 选项设置的属性的拼写和格式。如果传送了不正确的值，系统不会向您发出警告，MQ 将无法对这些属性进行设置。
-force
不影响任何属性。
执行操作，而无需用户确认。该选项仅适用于 -remove instance 选项，后者通常需要确认。
-h
不影响任何属性。
显示帮助。不执行命令行上的其它选项。
-javahome path
不影响任何属性。
指定替代 Java 2 兼容 JDK 的路径。默认使用捆绑的运行时。
-jrehome path
不影响任何属性。
指定 Java 2 JRE 的路径。
-ldappassword
password
将 imq.user_repository.
ldap.password 设置为指定密码。指定访问 LDAP 用户系统信息库的密码。请参见使用 LDAP 服务器管理用户系统信息库。
-license [name]
不影响任何属性。
指定装入一个与 MQ 产品版本的默认许可证不同的许可证。如果不指定许可证名称，该选项将列出系统中安装的所有许可证。根据所安装的 MQ 版本的不同，name 的取值也不同：pe（平台版，只具有基本功能）、try（平台版的 90 天试用企业功能）和 unl（企业版）。请参见产品版本。
-loglevel level
将 imq.broker.log.level 设置为指定级别。
将日志记录级别指定为下列四项之一：NONE、ERROR、WARNING 或 INFO。默认值是 INFO。更多信息，请参见日志记录器。
-metrics int
将 imq.metrics.report.
interval 设置为指定秒数。指定报告测量信息的时间间隔（以秒为单位）。
-name brokerName
将 imq.instancename 设置为指定名称。
指定该代理的实例名称，并使用相应的实例配置文件。如果不指定代理名称，文件名将设置为 imqbroker。
注：如果在同一台主机上运行了多个代理实例，每个实例必须具有唯一的名称。-passfile fileName
将 imq.passfile.
enabled 设置为 true。将 jmq.passfile.dirpath 设置为包含文件的路径。
将 imq.passfile.name 设置为该文件名。指定文件名，从该文件中可以读取 SSL 密钥存储、LDAP 用户系统信息库或 JDBC 兼容数据库的密码。更多信息，请参见使用密码文件。
-password keypassword
将 imq.keystore.
password 设置为指定密码。指定 SSL 证书密钥存储的密码。更多信息，请参见安全性管理器。
-port number
将 imq.portmapper.port 设置为指定端口号。
指定代理的端口映射器的端口号。默认情况下，该端口号设置为 7676。要在同一台服务器上运行两个代理实例，每个代理的端口映射器必须拥有不同的端口号。JMS 客户机使用该端口号连接到代理实例。
-remove instance
不影响任何属性。
导致代理实例被删除：删除与实例相关联的实例配置文件、日志文件、持久性存储器与其它文件和目录。除非指定 -force 选项，否则需要用户确认。
-reset store| messages|
durables|
props
不影响任何属性。
根据给定变量，重置代理实例的数据存储（或数据存储的子集）或配置属性。
重置数据存储将清除所有的持久性数据，包括持久性消息、长期订阅和事务信息。这使您可以启动一个完全清空的代理实例。也可以仅清除所有的持久性消息或仅清除所有的长期订阅。（如果不希望下次启动代理实例时重置持久性存储器，请勿使用 -reset 选项重新启动代理实例。）更多信息，请参见持久性管理器。
重置代理的属性，用一个空文件代替现有的实例配置文件 (config.properties)：所有的属性将使用默认值。
-restore fileName
不影响任何属性。
仅适用于代理群集。用指定的备份文件替换主管代理的配置更改记录。该文件必须是原来用 -backup 选项创建的那个备份文件。请参见恢复主管代理的配置更改记录。
-shared
将 imq.jms.
threadpool_model 设置为 shared。指定使用共享线程池模型来实现 jms 连接服务。在该模型中，连接之间共享线程，以增加代理实例支持的连接数量。更多信息，请参见连接服务。
-silent
将 imq.log.console.
output 设置为 NONE。停止向控制台记录日志信息。
-tty
将 imq.log.console.
output 设置为 ALL。指定在控制台上显示所有消息。默认情况下，只显示 WARNING 和 ERROR 级别的消息。
-version
不影响任何属性。
显示所安装产品的版本号。
-vmargs arg [[arg]...]
不影响任何属性。
指定传送到 Java VM 的变量。变量之间用空格分隔。如要传送多个变量，或是变量内包含空格，请使用闭合的引号。例如：
imqbrokerd -tty -vmargs "-Xmx128m -Xincgc"使用群集（企业版）
本节介绍用于配置多代理群集的属性，并介绍了连接代理的两种方法，并说明如何管理群集。关于群集的介绍，请参见多代理群集（企业版）。
使用群集时，请确保同一个群集中所有代理的主机时钟处于同步状态。
群集配置属性
将代理连接到群集时，所有连接的代理必须指定相同的群集配置属性值。这些属性说明了群集中代理的合作。表 5-3 概述了与群集相关的配置属性。
可以使用以下两种方法之一来设置群集属性：
- 可以在每个代理的实例配置文件中（或启动各个代理的命令行中）设置与群集相关的配置属性。例如，要连接代理 A（位于 host1、7676 端口）、代理 B（位于 host2、5000 端口）和代理 C（位于 ctrlhost、7676 端口），则代理 A、B 和 C 的实例配置文件需要设置如下属性。
imq.cluster.brokerlist=host1, host2:5000, ctrlhost
如果决定更改群集配置，此方法要求更新所有代理中与群集相关的属性。
- 在一个中心群集配置文件中设置群集配置属性。这些属性可能包括要连接的代理列表 (imq.cluster.brokerlist) 和主管代理的地址 (imq.cluster.masterbroker)，后一项为可选项。
如果使用该方法，还必须将群集中的每个代理的 imq.cluster.url 属性设置为指向群集配置文件的位置。从易于维护的角度出发，建议使用这种方法来配置群集。
以下代码范例显示了群集配置文件的内容。host1 和 ctrlhost 都是在默认端口上运行。这些属性指定 host1 和 ctrlhost 连接到一个群集中，并指定 ctrlhost 作为主管代理。
imq.cluster.brokerlist=host1,host2:5000,ctrlhost
imq.cluster.masterbroker=ctrlhost
连接到此群集中的每个代理的实例配置文件都必须包含群集配置文件的 URL，例如：
imq.cluster.url=file:/home/cluster.properties
连接代理
本节介绍将代理连接到群集中的两种方法。无论使用哪种方法，启动的每个代理将每隔五秒钟就尝试一次连接到其它代理。群集中的其它代理启动后，该尝试就会成功。
如果将代理连接到群集，并不一定要首先启动主管代理。如果群集中的某个代理在主管代理之前启动，该代理将保持暂停状态，拒绝客户机连接。主管代理启动后，暂停的代理将自动进入正常运行状态。
方法 1：无群集配置文件
将代理连接到群集的步骤
- 使用带有 -cluster 选项的 imqbrokerd 命令来启动代理，并将（要连接的）代理的完整列表指定为 -cluster 选项的变量。
- 请在启动要连接到群集的每个代理时执行该操作。
例如，以下命令启动了一个新代理，并将其连接到运行于 host1 的默认端口上的代理、运行于 host2 的 7677 端口上的代理和运行于 localhost 的 7678 端口上的代理。
imqbrokerd -cluster host1,host2:7677,:7678
方法 2：使用群集配置文件
也可以创建一个群集配置文件，来指定要连接的代理列表（可选：指定主管代理的地址）。这种定义群集的方法更适合生产系统。请注意，必须将群集中的每个代理的 imq.cluster.url 属性值设置为指向群集配置文件。
将代理添加到群集
设置代理群集后，可能需要添加新代理或重新启动群集中原有的代理。
要将新代理添加到现有群集，可以执行以下操作之一：
如果没有使用群集配置文件，那么启动新代理时，在命令行中使用 -D 选项指定 imq.cluster.brokerlist 和（如果必要）imq.cluster.masterbroker 属性。
将代理添加到群集中的步骤（如果是使用群集配置文件）
- 将新代理添加到群集配置文件中的 imq.cluster.brokerlist 属性。
- 对群集中的任何代理执行以下命令。
imqcmd reload cls
该命令强制所有的代理重新装入 imq.cluster.brokerlist 属性，以保证群集中代理的所有持久性信息都是最新的。
重新启动群集中的代理
要重新启动群集中的现有代理，可以执行以下操作之一：
- 如果使用群集配置文件定义群集，请在用于启动代理的命令行中使用 -D 选项来指定 imq.cluster.url 属性。
- 如果不是使用群集配置文件定义群集，那么启动新代理时，请在命令行中使用 -D 选项指定 imq.cluster.brokerlist 属性（如有必要，请一并指定 imq.cluster.masterbroker 属性）。如果群集中没有主管代理，可以在启动新代理仅使用 -cluster 选项来指定群集中的代理列表。
从群集中删除代理
从群集中删除代理时，请注意以下几点：
- 如果代理 A、B 和 C 均是使用以下命令行启动，那么仅仅重新启动 A 将无法将其从群集中删除。
imqbrokerd -cluster A,B,C
而是需要使用以下命令行重新启动所有的其它代理：
imqbrokerd -cluster B,C
然后，需要启动代理 A，且不指定 -cluster 选项。
- 如果代理列表是使用群集配置文件来指定，那么需要执行以下操作：
备份主管代理的配置更改记录
每个群集都可以拥有一个主管代理，它将记录群集的持久性状态的所有更改，包括对长期订阅和管理员创建的物理目标的更改。所有的代理在启动时都会咨询主管代理，以同步关于这些持久性对象的信息。因此，主管代理发生故障会影响整个群集。有鉴于此，使用 imqbrokerd 命令的 -backup 选项来定期备份主管代理的更改记录是很重要的。例如，
imqbrokerd -backup mybackuplog
请及时进行如上的备份操作，这很重要。恢复一个很旧的备份可能会导致丢失信息：该备份最后一次完成之后创建的任何持久性对象都将丢失。
恢复主管代理的配置更改记录
万一发生故障时恢复主管代理的步骤
- 关闭群集中的所有代理。
- 用以下命令恢复主管代理的配置更改记录：
imqbrokerd -restore mybackuplog
- 如果要给主管代理分配新名称或端口号，必须更新群集配置文件，指定主管代理是群集中的代理之一，并指定它的新名称（使用 imq.cluster.masterbroker 属性）。
- 重新启动所有代理。
恢复代理将不可避免地导致某些过时的数据重新装入到代理的配置更改记录中。不过，只要经常进行前一小节所介绍的定期备份，可以将这个问题的影响减到最小。
因为主管代理记录对持久性对象的所有更改的历史记录，所以每过一段时间其数据库就会有显著的扩充。备份和恢复操作有利于压缩和优化该数据库。
日志记录
本节介绍了代理的默认日志记录配置，并说明了如何更改该配置，从而将日志信息重定向到替代输出通道、更改转移标准以及报告代理的测量信息。关于日志记录的介绍，请参见日志记录器。
默认日志记录配置
启动代理时，系统自动将其配置为将日志输出保存到以下位置的一组滚动生成的日志文件中：
IMQ_VARHOME/instances/brokerName/log/
（在 Solaris 中为 /var/imq/instances/brokerName/log/）日志文件是纯文本文件。它们的名称如下（从最早生成到最近生成）：
log.txt
log_1.txt
log_2.txt
...
log_9.txt默认情况下，日志文件每星期转移一次；系统维护九个备份文件。
- 要更改保存日志文件的目录，请将 imq.log.file.dirpath 属性设置为所需的路径。
- 要将日志文件的根名称由 log 改为其它名称，请设置 imq.log.file.filename 属性。
代理支持三种日志种类：ERROR、WARNING 和 INFO（请参见表 2-7）。设置日志记录级别后，将收集所有高于和等于该级别的消息。默认日志级别是 INFO。这表示将记录 ERROR、WARNING 和 INFO 消息。
日志消息格式
记录的消息由时间戳、消息代码和消息本身构成。信息的大小取决于所设置的日志级别。以下是一个 INFO 消息的实例。
[13/Sep/2000:16:13:36 PDT] B1004 Starting the broker service using tcp [ 25374,100] with min threads 50 and max threads of 500
更改日志记录器配置
表 2-8 说明了所有的日志记录器属性。
更改代理的日志记录器配置的步骤
- 设置日志级别。
- 设置一个和多个日志记录种类的输出通道（文件、控制台或两者）。
- 如果将输出记录到文件中，请为该文件配置转移标准。
可以通过设置日志记录器属性完成上述步骤。可以使用以下两种方法之一来进行设置：
- 启动代理之前，在该代理的 config.properties 文件中更改或添加日志记录器属性。
- 在启动代理的 imqbrokerd 命令中指定日志记录器命令行选项。也可以使用代理选项 -D 来更改日志记录器属性（或任何代理属性）。
在命令行上传送的选项将覆盖代理实例配置文件中指定的属性。表 5-4 列出了影响日志记录的 imqbrokerd 选项。
以下小节介绍了如何更改默认配置，以执行以下操作：
- 更改输出通道（日志消息的目标）
- 更改转移标准
- 记录代理测量信息
更改输出通道
默认情况下，错误和警告消息除了记录到日志文件中以外，还会显示在终端上。（在 Solaris 中，错误消息还会写入到系统的系统日志守护程序中。）
可以用以下方式更改日志消息的输出通道：
- 要在屏幕上显示所有的日志种类（对于给定的级别）输出，请在 imqbrokerd 命令中使用 -tty 选项。
- 要阻止在屏幕上显示日志输出，请在 imqbrokerd 命令中使用 -silent 选项。
- 使用 imq.log.file.output 属性指定将哪些种类的日志记录信息写入到日志文件。例如，
imq.log.file.output=ERROR
- 使用 imq.log.console.output 属性指定将哪些种类的日志记录信息写入到控制台。例如，
imq.log.console.output=INFO
- 在 Solaris 中，使用 imq.log.syslog.output 属性指定将哪些种类的日志记录信息写入到 Solaris 系统日志中。例如，
更改转移标准
转移日志文件有两个标准：时间和大小。默认是使用时间标准，每七天转移一次文件。
- 要更改时间间隔，需要更改 imq.log.file.rolloversecs 属性。例如，以下属性定义将时间间隔更改为十天：
imq.log.file.rolloversecs=864000
- 要将转移标准更改为取决于文件大小，需要设置 imq.log.file.rolloverbytes 属性。例如，以下定义将在文件达到 500,000 字节的限制时将代理定向到转移文件。
imq.log.file.rolloverbytes=500000
如果同时设置与时间相关和与大小相关的转移属性，首先达到的限制将触发转移。如前所述，代理最多维护九个转移文件。
记录代理性能测量信息
代理的默认配置，包括以下设置：
- imq.metrics.enabled=true
- imq.metrics.interval=0
- imq.log.level=INFO
这些设置的结果是，代理收集它本身和活动连接服务的性能测量信息，但并不生成测量信息报告。
可以使用以下两种方法之一来使代理生成测量信息报告：
- 在 imqbrokerd 命令中使用 -metrics 选项，并指定代理生成报告的时间间隔（以秒为单位）。
- 将 imq.metrics.interval 属性设置为希望代理生成报告的时间间隔（以秒为单位）。
因为测量信息报告包含在 INFO 种类中，所以默认情况下，测量信息报告会被写入到日志文件输出通道。
以下所示为范例测量信息：
[31/Jan/2001:15:00:50 PST]
Connections:0 JVM Heap:6291456 bytes (5186320 free)
In:0 mesgs (0bytes) 0 pkts (0 bytes)
Out:0 mesgs (0bytes) 0 pkts (0 bytes)
Rate In:0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)
Rate Out:0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)
表 5-5 说明了对每个连接服务所生成的测量信息的含义。
表 5-6 介绍了对每个代理所收集和报告的测量信息。
表 5-6 对每个代理所收集的测量信息
测量信息
说明
VM heap size (bytes)
Java VM 堆的最大大小。
VM heap free space (bytes)
Java VM 堆中所剩可用空间的容量。
注 使用 imqcmd metrics 命令也可以获得该信息。