管理和配置指南


JBoss 企业级应用程序平台 6.2

适用于红帽 JBoss 企业版应用程序平台 6

Sande Gilda

David Le Sage

Red Hat Engineering Content Services

Darrin Mison

David Ryan

Misty Stanley-Jones

摘要

本书是安装和配置红帽 JBoss 企业版应用程序平台 6 及其补丁的指南。

第 1 章 简介

红帽 JBoss EAP 6 是一个构建在开放标准上并和 Java EE 6 规格兼容的快速的、安全的、功能强大的中间件平台。它集成 JBoss AS 7 和高可用性的群集、强大的 messaging 系统、分布式缓存以及其他技术来创建稳定、可扩充的和快速的平台。
新的模块化结构允许服务只在需要时才启用,这显著地提高了启动速度。管理控制台和管理命令行接口不需要手动编辑 XML 配置文件,并添加了创建脚本和自动化任务的能力。此外,它也包含了 API 和开发框架以快速开发安全的、强大的和可扩充的 Java EE 应用程序。

1.2. JBoss EAP 6 的功能

Expand
表 1.1. 6.1.0 功能
功能 描述
Java 认证 已认证的 Java EE 6 Full 和 Web 配置规格的实现。
受管域
  • 受管域提供对多个服务器实例和物理主机的集中式管理,而独立服务器则只允许单个的服务器实例。
  • 配置、部署、套接字绑定、模块、扩展和系统属性都可以根据每个服务器组进行管理。
  • 应用程序的安全性,包括安全域都集中管理以简化配置。
管理控制台和管理 CLI 管理控制台和管理 CLI 是管理域或独立 EAP 实例的全新接口。你不再需要编辑 XML 文件。管理 CLI 甚至可以提供批处理模式,你可以编写脚本并自动化管理任务。
简化的目录格式 EAP 的目录结构已经进行了简化。modules/ 目录现在包括了应用服务器模块,而不是使用公用的和服务器专有的 lib/ 目录。domain/standalone/ 目录包含了域和独立部署的 artifact 和配置文件。
模块化的类加载机制 你根据需要来加载和卸载模块以提高性能和增强安全性、以及更快的启动和重启速度。
流线型的数据源管理 数据库驱动可以像其他服务一样部署。此外,数据源可以在管理控制台和管理 CLI 里直接创建和管理。
更快的启动和停止速度 JBoss EAP 6 使用更少的资源且对系统资源的利用率非常高。这对于开发人员尤其有益处。

1.3. 关于 JBoss EAP 6 操作模式

JBoss EAP 提供两种操作 JBoss EAP 实例的模式,它可以引导为独立服务器(Standalone Server)受管域(Managed Domain)。每种模式都是为了满足不同商业场景的需要。它让您可以选择单个服务器安装还是多服务器管理以满足商业需求及自动化管理过程。
受管域或独立服务器的选择取决于如何管理服务器而不是它们为满足最终用户请求而提供的功能。对于高可用性(HA)群集这种区分尤其重要。理解 HA 功能和运行独立服务器还是受管域并不相关是很重要的,也就是说,一组独立服务器也可以组成 HA 群集。

1.4. 关于独立服务器

独立服务器是 JBoss EAP 的两种操作模式之一。独立服务器模式以独立的进程运行,它和以前的 JBoss EAP 版本的唯一运行模式类似。
作为独立服务器运行的 JBoss EAP 实例只是一个单一实例,但也可以运行在群集配置里。

1.5. 关于受管域

受管域是 JBoss EAP 的两种操作模式之一。它是一个通过单点控制来管理多个 JBoss EAP 6 实例的模式。
集中管理的服务器集合被称为域的成员。
域控制器是控制域的中心点。它确保每个服务器都可以按照域的管理策略进行配置。域控制器也是一个主机控制器。主机控制器是运行 domain.shdomain.bat 脚本的物理或虚拟主机。与域控制器不同,我们配置主机控制器来委托域管理任务。每台主机上的主机控制器和域控制器交互来控制运行在主机上的应用服务器实例的生命周期,并协助域控制器进行管理。每个主机都可以包含多个服务器组。服务器组是一系列安装了 JBoss EAP 6 的服务器实例,并将其作为一个整体来管理和配置。既然域控制器管理部署在服务器组上的配置和应用程序,服务器组里的每台服务器都共享相同的配置和部署。
域控制器、单个主机控制器和多个服务器是可以运行在相同物理系统上的相同 JBoss EAP 6 实例里的。主机控制器捆绑在专门的物理(或虚拟)主机上。如果使用不同的配置,您可以在相同的硬件上运行多个主机控制器,所以端口和其他资源并不会冲突。
受管域有一个域控制器,三个主机控制器以及三个服务器组。服务器是服务器组的成员,可以位于域里任意一个主机控制器上。

图 1.1. 受管域的图形表示方式

1.6. 关于域控制器

域控制器是一个充当域集中管理点的 JBoss EAP 6 服务器实例。您可以配置主机控制器为域控制器。域控制器的主要职责是:
  • 维护域的集中管理策略
  • 确保所有主机控制器可以知晓其当前的内容。
  • 协助主机控制器以确保所有运行的 JBoss EAP 6 实例都按照这个策略进行配置
集中管理策略默认保存在 domain/configuration/domain.xml 文件里,它位于域控制器的主机文件系统上解压的 JBoss EAP 6 安装目录里。
domain.xml 必须位于作为域控制器运行的主机控制器的 domain/configuration/ 目录里。这个文件对于不是作为域控制器的主机控制器上的安装来说并不是强制的,虽然 domain.xml 文件的出现也没有害处。domain.xml 文件包含不同配置集的配置,它们可都用于运行在域里的服务器实例。配置集的配置包含组成配置集的不同子系统的详细配置。域配置也包含对套接字组和服务器组的定义。

1.7. 关于域控制器失效切换

如果由于某种原因域控制器出现故障,你可以配置和提名任何主机控制器为域控制器。

1.8. 关于主机控制器

当脚本 domain.shdomain.bat script 运行在主机上时会启动主机控制器。主机控制器的主要职责是管理服务器。它委托域管理任务并负责启动和停止运行在主机上的单独的应用服务器进程。它和域控制器进行交互以帮助管理服务器和域控制器间的通讯。域里多个主机服务器可以和单个域控制器进行交互。因此,所有的主机控制器和运行在单一域模式下的服务器实例可以拥有单一的域控制器且必须属于相同的域。
每个主机控制器默认都从主机的文件系统上解压的 JBoss EAP 6 安装的 domain/configuration/host.xml 文件读取配置。host.xml 包含下列特定主机专有的配置信息:
  • 从这个安装位置运行的实际的 JBoss EAP 6 实例名称的列表
  • 任何下列的配置:
    • 主机控制器如何联系域控制器来注册自身并访问域配置
    • 如何找到并联系远程的域控制器
    • 告诉主机控制器自身充当域控制器
  • 这些条目是本地物理安装的配置。例如,domain.xml 里声明的命名接口定义可以映射到 host.xml 里实际的主机专有的 IP 地址。domain.xml 里的绝对路径名可以映射到 host.xml 里实际的文件系统路径。

1.9. 关于服务器组

服务器组是一个进行集中管理和配置的服务器实例集合。在受管域里,每个应用服务器实例都属于一个服务器组,即使它只是唯一的成员。组里的服务器实例共享相同的配置集和部署的内容。域控制器和主机控制器对域里的每个服务器组的所有服务器实例都强制实施标准的配置。域可以由多个服务器组组成。不同的服务器组可以用不同的配置集和部署来进行配置。例如,域里可以有提供不同服务的不同服务器层。不同的服务器组也可以有相同的配置集和部署,例如,为了在升级应用程序时避免服务中断,可以首先升级一个服务器组,然后再升级第二个服务组。
下面是一个服务器组定义示例:
     
<server-group name="main-server-group" profile="default">
 <socket-binding-group ref="standard-sockets"/>
  <deployments>
   <deployment name="foo.war_v1" runtime-name="foo.war"/>
   <deployment name="bar.ear" runtime-name="bar.ear"/>
  </deployments>
</server-group>

服务器组包括下列强制的属性:
  • name:服务器组的名称
  • profile:服务器组的配置集的名称
服务器组包含下列可选属性:
  • socket-binding-group:用于组里服务器的默认套接字绑定组的名称。在 host.xml 里可以对每个服务器覆盖这个名称。如果在 server-group 元素里没有提供 socket-binding-group 名称,那您必须在 host.xml 里为每个服务器提供一个名称。
  • deployments:部署在组里服务器上的部署内容
  • system-properties:组里服务器上设置的系统属性
  • jvm:组里所有服务器的默认 JVM。主机控制器将这些设置和 host.xml 里的其他配置进行合并以生成启动服务器的 JVM 的设置。

1.10. 关于 JBoss EAP 6 配置集

以前 JBoss EAP 版本里使用的配置集的概念不再使用了。JBoss EAP 6 现在使用更少的配置文件来保存配置信息。
模块和驱动是根据需要加载的,所以以前 JBoss EAP 6 版本里让服务器更高效地启动的 default 配置集的概念不再适用。在部署期间,模块依赖关系将被确定、排序且由服务器或域控制器进行解析,并按正确的顺序加载。在部署卸载期间,当没有部署需要模块时,它将被卸载。
您可以从配置里删除子系统来禁用模块或手动卸载驱动或其他服务。然而,大多数情况下这是不必要的。如果你的应用程序没有使用模块,它不会被加载。

第 2 章 应用服务器管理

2.1. 启动和停止 JBoss EAP 6

2.1.2. 将 JBoss EAP 6 作为独立服务器启动

概述

本节涵盖将 JBoss EAP 6 作为独立服务器启动的步骤

过程 2.1. 将平台服务作为独立服务器启动

  1. 对于红帽企业版 Linux。

    运行命令:EAP_HOME/bin/standalone.sh
  2. 对于 Microsoft Windows 服务器。

    运行命令:EAP_HOME\bin\standalone.bat
  3. 可选:指定其他的参数。

    要查看传入启动脚本的其他参数,请使用 -h 参数。
结果

JBoss EAP 6 服务器实例已启动。

2.1.3. 将 JBoss EAP 6 作为受管域启动

操作顺序

域控制器必须在域里任何服务器组里的任何从服务器之前启动。先在域控制器上,然后在每个关联的主机控制器和其他主机上使用这个过程。

过程 2.2. 将平台服务作为受管域启动

  1. 对于红帽企业版 Linux。

    运行命令: EAP_HOME/bin/domain.sh
  2. 对于 Microsoft Windows 服务器。

    运行: EAP_HOME\bin\domain.bat
  3. 可选:传递其他参数到启动脚本里。

    请使用 -h 参数来获取传递到启动脚本里的参数列表。
结果

JBoss EAP 6 受管域实例已启动。

2.1.4. 用替代配置启动 JBoss EAP 6

如果你没有指定配置文件,服务器将用默认的文件启动。然而,当你启动服务器时,你可以手动指定一个配置文件。启动过程会稍有不同,这取决于你是使用受管域还是独立服务器、以及你使用的操作系统。

前提条件

  • 在使用替代配置文件之前,请将 default 配置作为模版使用。对于受管域,配置文件必须位于 EAP_HOME/domain/configuration/ 目录。对于独立服务器,配置文件必须位于 EAP_HOME/standalone/configuration/ 目录。

注意

EAP_HOME/docs/examples/configs/ 目录里包含了几个配置示例。请用这些例子来启用额外的功能,如群集或 Transactions XTS API。

过程 2.3. 用其他配置启动实例

  1. 独立服务器

    对于独立服务器,请将配置文件的名称作为 --server-config 参数的选项。配置文件必须位于 EAP_HOME/standalone/configuration/ 目录里,而且您需要指定相对这个目录的路径。

    例 2.1. 在红帽企业版 Linux 里对独立服务器使用其他的配置文件

    [user@host bin]$ ./standalone.sh --server-config=standalone-alternate.xml
    这个例子使用了 EAP_HOME/standalone/configuration/standalone-alternate.xml 配置文件。

    例 2.2. 在 Microsoft Windows 服务器里对独立服务器使用其他的配置文件

    C:\EAP_HOME\bin>standalone.bat --server-config=standalone-alternate.xml
    这个例子使用了 EAP_HOME\standalone\configuration\standalone-alternative.xml 配置文件。
  2. 受管域

    对于受管域,请为 --domain-config 参数提供配置文件的名称。这个文件必须位于 EAP_HOME/domain/configuration/ 目录,且您需要指定相对这个目录的路径。

    例 2.3. 在红帽企业版 Linux 里对受管域使用其他的配置文件

    [user@host bin]$ ./domain.sh --domain-config=domain-alternate.xml
    这个例子使用了 EAP_HOME/domain/configuration/domain-alternate.xml 配置文件。

    例 2.4. 在 Microsoft Windows 服务器里对受管域使用其他的配置文件

    C:\EAP_HOME\bin>domain.bat --domain-config=domain-alternate.xml 
    
    
    这个例子使用了 EAP_HOME\domain\configuration\domain-alternate.xml 配置文件。
结果

使用替代配置运行了 JBoss EAP 6。

2.1.5. 停止 JBoss EAP 6

您停止 JBoss EAP 6 的方式取决于它是如何启动的。本节涵盖停止交互式启动的实例、停止作为服务启动的实例以及停止用脚本复制至后台进程的实例。

注意

本节不会涉及在受管域里停止服务器或服务器组。相关信息请参考 第 2.2.3 节 “使用管理控制台停止服务器”

过程 2.4. 停止 JBoss EAP 6 的独立服务器实例

  1. 停止从命令提示交互式启动的实例。

    在 JBoss EAP 6 运行的终端窗口里按 Ctrl-C
  2. 停止作为操作系统服务启动的实例。

    根据操作系统使用下列步骤。
    • 红帽企业版 Linux

      对于红帽企业版 Linux,如果您已经编写了服务脚本,请使用它的 stop 功能。这需要编写到脚本里。然后您可以使用 service scriptname stop,这里的 scriptname 是脚本名称。
    • Microsoft Windows Server

      在 Microsoft Windows 里,使用 net service 命令,或者通过控制面板里的 Services 小程序来停止服务。
  3. 停止在背景运行的示例(红帽企业版 Linux)

    1. 从进程列表里找到实例。一个选择是运行 ps aux |grep "[j]ava -server"。它会为运行在本地主机上的每个 JBoss EAP 6 实例返回一个结果。
    2. 运行 kill process_ID 给进程发送 TERM 信号,这里的 process_ID 是上面的 ps aux 命令的第二个字段的编号。
结果

每个方法都可以干净地关闭 JBoss EAP 6,所以不会丢失数据。

2.1.6. 服务器启动参数和开关参考

应用服务器启动脚本在运行时接受其他参数和开关。这些参数允许服务器根据 standalone.xmldomain.xmlhost.xml 配置文件里定义的其他配置启动。这可能包括用其他套接字绑定集或次级配置启动服务器。在启动时使用 help 开关可以参考这些可用的参数列表。

例 2.5. 

下面的例子和 第 2.1.2 节 “将 JBoss EAP 6 作为独立服务器启动” 里解释的服务器启动类似,但添加了 -h--help 开关。下表解释了 help 开关的结果。
[localhost bin]$ standalone.sh -h
Expand
表 2.1. 运行时开关和参数表
参数或开关 描述
--admin-only 设置服务器的运行类型为 ADMIN_ONLY。这将导致它打开管理接口并接受管理请求,但不会启动其他运行时服务或接受最终用户请求。
-b=<value> 设置系统属性 jboss.bind.address 为给定的值。
-b <value> 设置系统属性 jboss.bind.address 为给定的值。
-b<interface>=<value> 设置系统属性 jboss.bind.address.<interface> 为给定的值。
-c=<config> 要使用的服务器配置文件的名称。默认是 standalone.xml
-c <config> 要使用的服务器配置文件的名称。默认是 standalone.xml
--debug [<port>] 激活调试模式并用可选参数来指定端口。只有启动脚本支持才可以使用。
-D<name>[=<value>] 设置系统属性。
-h 显示帮助信息并退出。
--help 显示帮助信息并退出。
--read-only-server-config=<config> 要使用的配置文件的名称。它和 '--server-config' 和 '-c' 不同,因为原始文件不会被覆盖。
-P=<url> 从给定 URL 加载系统属性。
-P <url> 从给定 URL 加载系统属性。
--properties=<url> 从给定 URL 加载系统属性。
-S<name>[=<value>] 设置安全性属性。
--server-config=<config> 要使用的服务器配置文件的名称。默认是 standalone.xml
-u=<value> 设置系统属性 jboss.default.multicast.address 为给定的值。
-u <value> 设置系统属性 jboss.default.multicast.address 为给定的值。
-V 显示应用服务器版本并退出。
-v 显示应用服务器版本并退出。
--version 显示应用服务器版本并退出。

2.2. 启动和停止服务器

2.2.1. 用管理 CLI 启动或停止服务器。

您可以用管理 CLI 或管理控制台来启动和停止服务器。这两个管理工具都允许您控制单个独立服务器实例,或者选择性地管理受管域部署里的多个服务器。如果您在使用管理控制台,请参考 第 2.2.2 节 “使用管理控制台启动服务器” 里的说明。如果您在使用管理 CLI,针对独立服务器和受管域实例的过程是不一样。
用管理 CLI 启动或停止独立服务器。

独立服务器实例可以用命令行脚本启动,并用 shutdown 命令在管理 CLI 里关闭。如果你再次需要这个实例,请按照 第 2.1.2 节 “将 JBoss EAP 6 作为独立服务器启动” 里描述的过程再次启动。

例 2.6. 通过管理 CLI 停止独立服务器实例

[standalone@localhost:9999 /] shutdown
用管理 CLI 启动或停止受管域

如果你在运行受管域,管理控制台会允许你选择启动或关闭域里的特定服务器。这包括整个域里的服务器组,以及主机上的特定服务器实例。

例 2.7. 通过管理 CLI 停止受管域里的服务器主机

和独立服务器实例类似, shutdown 命令用于关闭声明的受管域主机。这个例子通过在调用关闭操作前声明实例名来关闭名为 master 的服务器主机。请用 tab 健来协助完成字符串并开放可见变量如可用的主机值。
[domain@localhost:9999 /] /host=master:shutdown

例 2.8. 通过管理 CLI 停止受管域里的服务器组

这个例子通过在调用 startstop 操作前声明组启动了一个名为 main-server-group 的默认服务器组。请用 tab 健来协助完成字符串并开放可见变量如可用的主机组名的值。
[domain@localhost:9999 /] /server-group=main-server-group:start-servers
[domain@localhost:9999 /] /server-group=main-server-group:stop-servers

例 2.9. 通过管理 CLI 停止受管域里的服务器实例

这个例子通过在调用 startstop 操作前声明主机启动和停止了 master 主机上的一个名为 server-one 的服务器实例。请用 tab 健来协助完成字符串并开放可见变量如可用的主机和服务器配置的值。
[domain@localhost:9999 /] /host=master/server-config=server-one:start
[domain@localhost:9999 /] /host=master/server-config=server-one:stop

2.2.2. 使用管理控制台启动服务器

过程 2.5. 启动服务器

  1. 进入管理控制台里的 Server Instances

    1. 从控制台的顶部选择 Runtime 标签页。
  2. 选择服务器

    Server Instances 列表里,选择要启动的服务器。正在运行的服务器会用一个复选框标记表示。
    在这个列表的实例上悬停会在服务器细节下面以蓝色字体显示选项。
  3. 点击 Start

    要启动这个实例,请在 Start Server 文本出现时点击它。然后会出现一个确认对话框,点击 Confirm 按钮启动服务器。
结果

所选的服务器已启动并在运行中。

2.2.3. 使用管理控制台停止服务器

过程 2.6. 使用管理控制台停止服务器

  1. 进入管理控制台里的 Hosts, groups and server instances

    1. 从控制台的顶部选择 Runtime 比标签页。Topology 标签页里的主面板会显示可用的服务器实例。
  2. 选择服务器

    Server Instances 列表里,选择要停止的服务器。正在运行的服务器用一个复选框标记表示。
  3. 点击 Stop Server 文本

    点击当您将鼠标悬停在服务器条目时出现的 Stop Server 文本。确认对话框将会出现。
  4. 点击 Confirm 按钮来停止服务器。
结果

所选的服务器已停止。

2.3. 文件系统路径

2.3.1. 文件系统路径

JBoss EAP 6 使用了文件系统路径的逻辑名称。domain.xmlhost.xmlstandalone.xml 配置都包含一个可以声明路径的部分。然后配置的其他部分可以通过逻辑名称引用这些路径,避免了为每个实例声明绝对路径。这有利于配置和管理,因为它允许将专有的主机配置解析为同一的逻辑名称。
例如,日志子系统配置包括对 jboss.server.log.dir 路径的引用,它指向服务器的 log 目录。

例 2.10. 日志目录的相对路路径示例

<file relative-to="jboss.server.log.dir" path="server.log"/>

JBoss EAP 6 自动提供大量的标准路径而无需用户在配置文件进行配置。
Expand
表 2.2. 标准路径
描述
jboss.home.dir JBoss EAP 6 的根目录。
user.home 用户的主目录。
user.dir 用户的当前工作目录。
java.home Java 的装路径
jboss.server.base.dir 单独服务器实例的根目录。
jboss.server.data.dir 服务器用于持久性数据文件存储的目录。
jboss.server.config.dir 包含服务器配置的目录。
jboss.server.log.dir 服务器用于日志文件存储的目录。
jboss.server.temp.dir 服务器用于临时文件存储的目录。
jboss.controller.temp.dir 主机控制器用于临时文件存储的目录。
用户可以在配置文件里添加 path 元素来添加自己的路径,或覆盖除了上面前 5 个路径外的所有路径。下面的例子展示了相对于独立服务器实例的根目录的新的相对路径声明。

例 2.11. 相对路径的格式

<path name="examplename" path="example/path" relative-to="jboss.server.data.dir"/>

路径声明的结构使用下列属性。
Expand
表 2.3. 路径属性
属性 描述
name 路径的名称。
path 实际的文件系统路径。它将被当作绝对路径,除非指定了 relative-to 属性,此时它会被当作相对该路径的值。
relative-to 可选属性,它指定之前命名路径的名称,或者系统提供的标准路径中的其中一个。
domain.xml 配置文件里的 path 元素只要求 name 属性。它不需要包括指定下面例子里所展示的实际文件系统路径的信息。

例 2.12. 域路径示例

<path name="example"/>

这个配置简单地声明一个名为 example 的路径,可供 domain.xml 配置的其他部分引用。example 声明的实际文件系统位置是加入域组的主机实例的 host.xml 配置文件所专有的。如果使用了这个方法,每台主机的 host.xml 里必须有一个 path 元素来指定实际的文件系统路径。

例 2.13. 主机路径示例

<path name="example" path="path/to/example" />

standalone.xml 里的 path 元素必须包括实际文件系统路径的规格。

2.4. 配置文件历史

2.4.1. 关于 JBoss EAP 6 配置文件

JBoss EAP 6 的配置和以前版本已经有了很大的修改。最显著的不同是使用了简化的配置文件结构,它包含下面列出的一个或多个文件。
Expand
表 2.4. 配置文件的位置
服务器模式 位置 目的
domain.xml EAP_HOME/domain/configuration/domain.xml 这是受管域的主配置文件。只有域主控制器可以读取这个文件。对于其他成员,它可以被删除。
host.xml EAP_HOME/domain/configuration/host.xml 这个文件包含了受管域里的物理主机专有的配置细节,如网络接口、套接字绑定、主机名称和其他主机专有的细节。host.xml 文件包含了 host-master.xmlhost-slave.xml 的全部功能,正如下面所描述的。这个文件没有出现在独立服务器里。
host-master.xml EAP_HOME/domain/configuration/host-master.xml 这个文件包含了作为受管域里主服务器运行所需的配置细节。这个文件不会出现在独立服务器里。
host-slave.xml EAP_HOME/domain/configuration/host-slave.xml 这个文件包含了作为受管域里从服务器运行所需的配置细节。这个文件不会出现在独立服务器里。
standalone.xml EAP_HOME/standalone/configuration/standalone.xml 这是用于独立服务器的默认配置文件。它包含了独立服务器的所有信息,如子系统、网络、部署、套接字绑定和其他配置细节。当您启动独立服务器时会自动使用这个配置。
standalone-full.xml EAP_HOME/standalone/configuration/standalone-full.xml 这是用于独立服务器的配置示例。它包含对每种可能的子系统的支持,除了那些要求高可用性的子系统。要使用它,请停止您的服务器并用下列命令重启:EAP_HOME/bin/standalone.sh -c standalone-full.xml
standalone-ha.xml EAP_HOME/standalone/configuration/standalone-ha.xml 这个配置文件示例启用所有的默认子系统并为独立服务器添加了 mod_cluster 和 JGroups 子系统,所以它可以参与高可用性或负载平衡群集。这个文件不适用于受管域。要使用这个配置,请停止您的服务器并用下列命令重启:EAP_HOME/bin/standalone.sh -c standalone-ha.xml
standalone-full-ha.xml EAP_HOME/standalone/configuration/standalone-full-ha.xml 这是用于独立服务器的配置示例。它包含对每种可能的子系统的支持,包含那些要求高可用性的子系统。要使用它,请停止您的服务器并用下列命令重启:EAP_HOME/bin/standalone.sh -c standalone-full-ha.xml
这些只是默认的位置。您可以在运行时指定不同的配置文件。

2.4.2. 配置文件历史

应用服务器的配置文件包括 standalone.xmldomain.xmlhost.xml。虽然您可以直接编辑这些文件,我们推荐用可用的管理操作(如管理 CLI 或管理控制台)来配置应用服务器模型。
为了协助维护和管理服务器实例,应用服务器在启动时创建了原始配置文件的带时间戳的版本。管理操作导致的任何其他的配置修改都会让原始文件自动备份,而实例的一个工作备份会保留以供引用或回滚。这个归档功能可以扩展为保存、加载和删除服务器配置的快照,从而允许回调和回滚场景。

2.4.3. 用以前的配置启动服务器

下面的例子展示了如何用独立服务器的 standalone.xml 里的以前的配置启动应用服务器。相同的概念也适用于受管域的 domain.xmlhost.xml
这个例子回调了管理操作修改服务器模型时应用服务器自动保存的配置。
  1. 确定您要启动的备份版本。这个例子将回调成功引导后第一次修改前的服务器模型的实例。
    EAP_HOME/configuration/standalone_xml_history/current/standalone.v1.xml 
  2. 传入 jboss.server.config.dir 下的相对文件名,用备份模型的配置启动服务器。
    EAP_HOME/bin/standalone.sh --server-config=standalone_xml_history/current/standalone.v1.xml 
结果

应用服务器用所选的配置启动了。

2.4.4. 使用管理 CLI 保存配置快照

总结

配置快照是当前服务器配置的时间点拷贝。管理员可以保存和加载这些拷贝。

下面的例子使用了 standalone.xml 配置文件,但相同的过程适用于 domain.xmlhost.xml 配置文件。

过程 2.7. 创建配置快照并保存

  • 保存快照

    运行 take-snapshot 操作来创建当前服务器配置的快照。
    [standalone@localhost:9999 /] :take-snapshot
    {
        "outcome" => "success",
        "result" => "/home/User/EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20110630-172258657standalone.xml"
    
结果

保存了当前服务器配置的快照。

2.4.5. 使用管理 CLI 加载配置快照

配置快照是当前服务器配置的时间点拷贝。管理员可以保存和加载这些拷贝。加载快照的过程和用于 第 2.4.3 节 “用以前的配置启动服务器” 的方法类似,都是从命令行而不是管理 CLI 界面运行来创建、列出和删除快照。
下面的例子使用了 standalone.xml 配置文件,但相同的过程适用于 domain.xmlhost.xml 配置文件。

过程 2.8. 加载配置快照

  1. 确定要加载的快照。这个例子将从 snapshot 目录回调下列文件。下面是快照文件的默认路径。
    EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20110812-191301472standalone.xml
    快照是用相对路径表达的,上面的例子可以像下面这样编写。
    jboss.server.config.dir/standalone_xml_history/snapshot/20110812-191301472standalone.xml
  2. 通过传入文件名用所选的配置快照启动服务器。
    EAP_HOME/bin/standalone.sh --server-config=standalone_xml_history/snapshot/20110913-164449522standalone.xml
结果

服务器用加载快照里选择的配置进行了重启。

2.4.6. 使用管理 CLI 删除配置快照

配置快照是当前服务器配置的时间点拷贝。管理员可以保存和加载这些拷贝。
下面的例子使用了 standalone.xml 配置文件,但相同的过程适用于 domain.xmlhost.xml 配置文件。

过程 2.9. 删除专有的快照

  1. 确定要删除的快照。这个例子将从 snapshot 目录删除下列文件。
    EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20110630-165714239standalone.xml
  2. 如下例所示,指定快照的名称,运行 :delete-snapshot 命令来删除专有的快照。
    [standalone@localhost:9999 /] :delete-snapshot(name="20110630-165714239standalone.xml")
    {"outcome" => "success"}
    
结果

快照已被删除。

过程 2.10. 删除所有快照

  • 如下例所示,运行 :delete-snapshot(name="all") 命令删除所有的快照。
    [standalone@localhost:9999 /] :delete-snapshot(name="all")
    {"outcome" => "success"}
    
结果

所有快照都已被删除。

2.4.7. 使用管理 CLI 列出所有的配置快照

配置快照是当前服务器配置的时间点拷贝。管理员可以保存和加载这些拷贝。
下面的例子使用了 standalone.xml 配置文件,但相同的过程适用于 domain.xmlhost.xml 配置文件。

过程 2.11. 列出所有的配置快照

  • 列出所有快照

    :list-snapshots 命令列出所有保存的快照。
    [standalone@localhost:9999 /] :list-snapshots
    {
        "outcome" => "success",
        "result" => {
            "directory" => "/home/hostname/EAP_HOME/standalone/configuration/standalone_xml_history/snapshot",
            "names" => [
                "20110818-133719699standalone.xml",
                "20110809-141225039standalone.xml",
                "20110802-152010683standalone.xml",
                "20110808-161118457standalone.xml",
                "20110912-151949212standalone.xml",
                "20110804-162951670standalone.xml"
            ]
        }
    }
    
结果

快照被列出。

第 3 章 管理接口

3.1. 管理应用服务器

JBoss EAP 6 提供了多个管理工具来配置和管理你的实现。其中包括新的管理控制台和管理命令行界面(CLI),以及让专家用户可以开发自己的工具的底层管理 API。

3.2. 管理应用程序编程接口(API)

管理客户

JBoss EAP 6 提供了不同的方法来配置和管理服务器,您可以使用 web 界面、命令行客户或一系列的 XML 配置文件。我们推荐的方法是编辑配置文件,包括管理控制台和管理 CLI。对配置文件的编辑总会在不同视图里同步并最终持久化到 XML 文件里。请注意,在服务器实例运行时对 XML 配置文件的修改将被服务器模型所覆盖。

HTTP API

管理控制台是用 Google Web Toolkit (GWT) 构建的 Web 界面的例子。管理控制台和服务器通过 HTTP 管理接口进行通讯。HTTP API 端点是依赖于 HTTP 协议来集成管理层的管理客户的入口点。它使用 JSON 编码协议和 de-typed RPC 风格的 API 来描述和执行管理操作。 HTTP API 用于 Web 控制台,它也为许多其他客户提供了集成能力。

HTTP API 端点和主机控制器或独立服务器是共存的。HTTP API 端点服务两种不同的上下文,一个用于执行管理操作,令为一个用于访问 Web 界面。在默认情况下,它运行在端口 9990 上。

例 3.1. HTTP API 配置文件示例

<management-interfaces>
  [...]
  <http-interface security-realm="ManagementRealm">
     <socket-binding http="management-http"/>
  </http-interface>
</management-interfaces>
Web 控制台是通过和 HTTP 管理 API 相同的端口来访问的。区别作为默认的本地主机访问的管理控制台、通过专门主机和端口远程访问的管理控制台和开放的域 API 是很重要的。
Expand
表 3.1. 访问管理控制台的 URL
URL 描述
http://localhost:9990/console 访问本地主机的管理控制台,它控制受管域的配置。
http://hostname:9990/console 远程访问管理控制台的主机命名和受管域配置。
http://hostname:9990/management 和管理控制台运行在相同端口上的 HTTP 管理 API,它显示原始属性和开放给 API 的值。
Native API

管理 CLI 就是 Native API 工具的一个例子。这个管理工具可用于受管域及独立服务器,它允许用户连接到域控制器或独立服务器实例并执行 de-typed 管理模型里可用的管理操作。

Native API 端点是依赖于原生协议来集成管理层的管理客户的入口点。它使用开放的二进制协议和基于非常少量的 Java 类型的 RPC 风格的 API 来描述和执行管理操作。它被管理 CLI 工具所使用,但也为很多其他客户提供了集成能力。
Native API 端点和主机控制器或独立服务器是共存的。使用管理 CLI 必须启用它。在默认情况下,它运行在端口 9999 上。

例 3.2. Native API 配置文件示例

<management-interfaces>
  <native-interface security-realm="ManagementRealm">
    <socket-binding native="management-native"/>
  </native-interface>
  [...]
</management-interfaces>

3.3. 关于管理控制台和管理 CLI

在 JBoss EAP 6 里,所有的服务器实例和配置都通过管理界面而不是编辑 XML 文件来进行配置。虽然 XML 配置文件仍可进行编辑,通过管理界面的管理提供了额外校验和服务器实例持久性管理的高级功能。服务器运行时对 XML 配置文件的修改仍会被服务器模型覆盖,任何添加的 XML 注释都会被删除。当服务器实例在运行时,我们应该只使用管理界面来修改配置文件。
要通过 Web 浏览器里的图形化用户界面来管理服务器,请使用管理控制台。
要通过命令行界面来管理服务器,则请使用管理 CLI。

3.4. 管理控制台

3.4.1. 管理控制台

管理控制台是用于 JBoss EAP 6 的基于 Web 的管理工具。
您可以使用管理控制台来启动和停止服务器、部署和卸载应用程序、调整系统设置并对服务器配置进行持久性修改。管理控制台也可以执行管理任务,并在修改需要服务器实例重启或重载时进行实时通知。
在受管域里,相同域里的服务器实例和服务器组可以通过域控制器的管理控制台进行集中管理。

3.4.2. 登录到管理控制台

前提条件

  • JBoss EAP 6 服务器必须正在运行。

过程 3.1. 登录到管理控制台

  1. 进入管理控制台开始页面

    通过 Web 浏览器进入管理控制台。默认的位置是 http://localhost:9990/console/,其中的 9990 是预定义为管理控制台的套接绑定的。
  2. 登录到管理控制台

    输入您之前创建的帐号的用户名和密码来登录到管理控制台屏幕。
    管理控制台的登录屏幕

    图 3.1. 管理控制台的登录屏幕

结果

登录后,下面的管理控制台登录页面将出现:
受管域
独立服务器

3.4.3. 修改管理控制台的语言

基于 Web 的管理控制台默认使用英语,但您可以选择下列语言。

所支持的语言

  • 德语 (de)
  • 简体中文 (zh-Hans)
  • 巴西葡萄牙语 (pt-BR)
  • 法语 (fr)
  • 西班牙语 (es)
  • 日语 (ja)

过程 3.2. 修改基于 Web 的管理控制台的语言

  1. 登录到管理控制台。

    登录到基于 Web 的管理控制台。
  2. 打开 Setting 对话框。

    屏幕的右下角是 Settings 标签。点击它打开管理控制台的设置对话框。
  3. 选择语言。

    Locale 选择框里选择语言。然点选择 Save。确认框通知您需要重载应用程序。点击 Confirm。刷新 Web 浏览器以使用新的区域设置。

3.4.4. 使用管理控制台配置服务器

过程 3.3. 配置服务器

  1. 进入管理控制台里的 Server Configurations 面板。

    1. 从控制台的顶部选择 Hosts 标签页。可用的服务器将显示在表格里。
  2. 编辑服务器配置

    1. Available Server Configurations 表格里选择服务器实例。
    2. 在所选的服务器下方选择 Edit 按钮。
    3. 修改配置属性。
    4. 在服务器列表下方选择 Save 按钮。
结果

服务器配置被修改,且会在服务器重启时生效。

3.4.5. 在管理控制台里添加部署

过程 3.4. 添加和验证部署

  1. 进入管理控制台的 Manage Deployments 面板

    1. 选择控制台顶部的 Runtime 标签页。
    2. 对于独立服务器,展开控制台左侧的 Server 菜单项并选择Manage Deployments。对于受管域,展开控制台左侧的 Domain 菜单项并选择 Manage Deployments
    Manage Deployments 面板将会出现。
  2. 添加部署内容

    点击 Content Repository 标签页上的 Add 按钮。Create Deployment 对话框将会出现。
  3. 选择要部署的文件

    在这个对话框里,点击 Browse 按钮。选择您要部署的文件。选好文件后点击 Next 按钮进行。
  4. 验证部署名

    验证出现在 Create Deployments 对话框里的部署名和 runtime 名称。验证名称后请点击 Save 按钮上传文件。
结果

所选的内容被上传至服务器且可以进行部署了。

3.4.6. 在管理控制台里创建新的服务器

过程 3.5. 创建新的服务器配置

  1. 进入管理控制台里的 Server Configurations 页面

    从控制台的右上角选择 Server 标签页。
  2. 创建新的配置

    1. 点击 Server Configuration 面板顶部的 Add 按钮。
    2. 编辑 Create Server Configuration 对话框里的基本服务器设置。
    3. 点击 保存 按钮保存新的服务器配置。
结果

新服务器被创建且出现在 Server Configurations 列表里。

3.4.7. 用管理控制台修改默认的日志级别

过程 3.6. 编辑日志级别

  1. 进入管理控制台的 Logging 面板

    1. 对于受管域,选择控制台顶部的 Profiles 标签页,然后从控制台左侧的下拉菜单里选择相关的配置集。
    2. 对于受管域或独立服务器,展开控制台左侧菜单的 CoreLogging 菜单并点击 Logging 条目。
    3. 点击控制台顶部的 Log Categories 标签页。
  2. 编辑 logger 细节

    编辑 Log Categories 表格里条目的细节。
    1. Log Categories 表格里选择条目,然后点击下面的 Details 部分里的 Edit 按钮。
    2. 通过 Log Level 下拉框选择类别的日志级别。完成后点击 Save 按钮。
结果

相关类别的日志级别已被更新。

3.4.8. 在管理控制台里创建新的服务器组

过程 3.7. 配置和添加新的服务器组

  1. 进入 Server Groups 视图

    选择右上角的 Hosts 标签页。
  2. 选择左侧的 Server 菜单的 Server Groups 标签页。
  3. 添加服务器组

    点击 Add 按钮来添加新的服务器组。
  4. 配置服务器组

    1. 输入服务器组的名称。
    2. 选择您添加服务器组的配置集。
    3. 选择您添加服务器组的套接字绑定。
    4. 点击 Save 按钮来保存新的组。
结果

新创建的服务器组出现在管理控制台里了。

3.5. 管理 CLI

管理 CLI 是 JBoss EAP 6 的一个命令行管理工具。
使用管理 CLI 启动和停止服务器、部署和卸载应用程序、配置系统设置并执行其他管理任务。操作可以批量模式进行,将多个任务作为一个组来运行。

3.5.2. 启动管理 CLI

过程 3.8. 在 Linux 或 Windows 里启动 CLI

    • 在 Linux 里启动 CLI

      运行 EAP_HOME/bin/jboss-cli.sh 命令:
      $ EAP_HOME/bin/jboss-cli.sh
    • 在 Windows 里启动 CLI

      运行 EAP_HOME\bin\jboss-cli.bat 命令:
      C:\>EAP_HOME\bin\jboss-cli.bat

3.5.3. 退出管理 CLI

过程 3.9. 退出管理 CLI

  • 运行 quit 命令

    在管理 CLI 里,输入 quit 命令:
    [domain@localhost:9999 /] quit
    Closed connection to localhost:9999

3.5.4. 用管理 CLI 连接受管服务器实例

过程 3.10. 连接至受管服务器实例

  • 运行 connect 命令

    在管理 CLI 里,输入 connect 命令:
    [disconnected /] connect
    Connected to domain controller at localhost:9999
    • 或者,在 Linux 系统里启动管理 CLI 时使用 --connect 参数来连接至受管服务器:
      $ EAP_HOME/bin/jboss-cli.sh --connect
    • --connect 参数可以用来指定服务器的主机和端口。要连接至地址 192.168.0.1 和端口 9999,请使用下列命令:
      $ EAP_HOME/bin/jboss-cli.sh --connect --controller=192.168.0.1:9999

3.5.5. 用管理 CLI 获取帮助

概述

管理 CLI 有带有普通和上下文敏感选项的帮助对话框。对于独立服务器和域控制器,依赖于操作上下文的 help 命令都要求已建立的连接。除非连接已建立,否则这些命令不会出现在列表里。

过程 3.11. 普通和上下文敏感帮助

  1. 运行 help 命令

    在管理 CLI 里,输入 help 命令:
    [standalone@localhost:9999 /] help
  2. 获取上下文敏感帮助

    在管理 CLI 里,输入 help -commands 扩展命令:
    [standalone@localhost:9999 /] help --commands
  3. 关于特定命令的更多详情,请运行 help 并以 '--help' 为参数。
    [standalone@localhost:9999 /]  deploy --help
结果

CLI 帮助信息被显示。

3.5.6. 以批模式使用管理 CLI

概述

批处理允许大量的操作请求按序列进行分组,然后作为一个单元来执行。如果序列里的任何以一个操作请求执行失败,整个操作组都将回滚。

过程 3.12. 批处理模式命令和操作

  1. 启用批处理模式

    batch 命令启用批处理模式。
    [standalone@localhost:9999 /] batch
    [standalone@localhost:9999 / #]
    提示里的井号(#)指明了批处理模式
  2. 添加操作请求到批处理命令里

    在批处理模式下,照常输入操作请求。操作请求将按输入的顺序添加到批处理命令里。
    关于格式化操作请求的详情,请参考 第 3.5.8 节 “在管理 CLI 里使用操作和命令”
  3. 运行批处理命令

    一旦输入了整个操作请求序列,请用 run-batch 运行这个批处理命令。
    [standalone@localhost:9999 / #] run-batch
    The batch executed successfully.
    关于可用于批处理的完整的命令列表,请参考 第 3.5.7 节 “CLI 批处理模式命令”
  4. 保存在外部文件里的批命令

    频繁运行的批处理命令可以存储在外部文件里,通过将完整文件路径作为参数传入 batch 或直接作为 run-batch 命令的参数来执行。
    您可以用文本编辑器创建批处理命令文件。每个命令都必须单独一行且 CLI 应该可以访问它。
    下面的命令将加载 myscript.txt 文件至批处理模式。这个文件里的所有命令都可以编辑或删除,您也可以插入新的命令。这个批处理会话里进行的修改不会持久化到 myscript.txt 文件里。
    [standalone@localhost:9999 /] batch --file=myscript.txt
    下面的命令将立即运行存储在文件 myscript.txt 里的批命令
    [standalone@localhost:9999 /] run-batch --file=myscript.txt
结果

输入的操作请求序列以批模式完成了。

3.5.7. CLI 批处理模式命令

这个表提供了 JBoss EAP 6 CLI 里可用的批处理命令列表。这些命令只能用于批处理模式。
Expand
表 3.2. CLI 批处理模式命令
命令名 描述
list-batch 当前批次里的命令和操作的列表。
edit-batch-line line-number edited-command 通过行号和要编辑的命令来编辑当前批处理里的行。例如: edit-batch-line 2 data-source disable --name=ExampleDS
move-batch-line fromline toline 指定您要移动的行号为第一个参数且新的位置为第二个参数来重新对批处理命令里的行进行排序。例如: move-batch-line 3 1
remove-batch-line linenumber 删除指定行上的批处理命令。例如: remove-batch-line 3
holdback-batch [batchname]
如果您突然想在 CLI 里执行批处理之外的命令,您可以使用这个命令推迟或存储当前的批处理命令。要返回已暂停批模式,只要在 CLI 命令行上再次输入 batch 就可以了。
如果在 holdback-batch 命令时您提供了 batchname,批命令将按照这个名称进行存储要返回命名的批次,请使用 batch batchname。不使用 batchname 调用 batch 命令将启动新的(未命名)的批处理。系统里只能有一个未命名的暂停批命令。
要查看暂停批命令的列表,请使用 batch -l 命令。
discard-batch 取消当前活动的批处理命令。

3.5.8. 在管理 CLI 里使用操作和命令

过程 3.13. 创建、配置和执行请求

  1. 构造操作请求

    操作请求允许和管理模型的低层交互。它们提供一种可控的方式来编辑服务器配置。操作请求由三部分组成:
    • 地址,前缀为斜杠(/)。
    • 操作名称,前缀为分号(:)。
    • 可选的参数,包含在括号(())里。
    1. 确定地址

      配置以有地址的资源层级树型出现。每个资源节点都提供了一系列不同的操作。地址指定哪些资源可以执行操作。地址使用下面的语法:
      /node-type=node-name
      • node-type 是资源节点的类型。它映射配置 XML 文件里的元素名称。
      • node-name 是资源节点的名称。它映射配置 XML 文件里的元素的 name 属性。
      • 用斜杠(/)分隔资源树的每个级别。
      要确定所需的地址,请参考 XML 配置文件。EAP_HOME/standalone/configuration/standalone.xml 文件保存独立服务器的配置信息,EAP_HOME/domain/configuration/domain.xmlEAP_HOME/domain/configuration/host.xml 文件保存受管域的配置信息。

      例 3.3. 操作地址示例

      要执行 Logging 子系统上的操作,请使用操作请求里的下列地址:
      /subsystem=logging
      要执行 Java 数据源上的操作,请使用操作请求里的下列地址:
      /subsystem=datasources/data-source=java
    2. 确定操作

      对于不同类型的资源节点,操作会有所不同。操作使用下面的语法:
      :operation-name
      • operation-name 是要请求的操作的名称。
      在独立服务器上的任何资源地址上使用 read-operation-names 操作来列出可用的操作。

      例 3.4. 可用的操作

      要列出 Logging 子系统到所有可用的操作,在独立服务器里输入下列请求:
      [standalone@localhost:9999 /] /subsystem=logging:read-operation-names
      {
          "outcome" => "success",
          "result" => [
              "add",
              "read-attribute",
              "read-children-names",
              "read-children-resources",
              "read-children-types",
              "read-operation-description",
              "read-operation-names",
              "read-resource",
              "read-resource-description",
              "remove",
              "undefine-attribute",
              "whoami",
              "write-attribute"
          ]
      }
      
    3. 确定任何参数

      每个操作可能需要不同的参数。
      参数使用下面的语法:
      (parameter-name=parameter-value)
      • parameter-name 是参数的名称。
      • parameter-value 是参数的值。
      • 多个参数用逗号隔开(,)。
      要确定所需的参数,在资源节点上执行 read-operation-description 命令,将操作名称作为参数传入。详情请参考 例 3.5 “确定操作的参数”

      例 3.5. 确定操作的参数

      要确定 logging 子系统上的 read-children-types 操作的必需参数,请输入 read-operation-description 命令:
      [standalone@localhost:9999 /] /subsystem=logging:read-operation-description(name=read-children-types)
      {
          "outcome" => "success",
          "result" => {
              "operation-name" => "read-children-types",
              "description" => "Gets the type names of all the children under the selected resource",
              "reply-properties" => {
                  "type" => LIST,
                  "description" => "The children types",
                  "value-type" => STRING
              },
              "read-only" => true
          }
      }
      
  2. 输入完整的操作请求

    一旦确定了地址、操作和所有参数,请输入完整的操作请求。

    例 3.6. 操作请求示例

    [standalone@localhost:9999 /] /subsystem=web/connector=http:read-resource(recursive=true)
结果

管理接口执行服务器配置里的操作请求。

3.5.9. 管理 CLI 命令参考

总结

第 3.5.5 节 “用管理 CLI 获取帮助” 描述了如何访问管理 CLI 的帮助功能,包括有带有普通和上下文敏感选项的帮助对话框。对于独立服务器和域控制器,依赖于操作上下文的 help 命令都要求已建立的连接。除非连接已建立,否则这些命令不会出现在列表里。

Expand
表 3.3. 
命令 描述
batch 通过创建新的批次、或者重新激活现有的暂停的批次来启动批模式。如果没有暂停的批命令,这个命令将启动新的批次。如果存在未命名的暂停的批命令,这个命令将重新激活它。如果存在有名称的暂停的批命令,将这个批次的名称作为参数来执行命令就可以激活。
cd 根据参数修改当前的节点路径。当前的节点路径用于不包含地址部分的操作请求的地址。如某个操作请求包含了地址,所包含的地址将当作当前节点路径的相对地址。当前的节点路径可以以节点类型结尾。此时,执行指定节点名称的操作就足够了,例如 logging:read-resource。
clear 清除屏幕。
command 允许您添加、删除和列出现有的普通类型的命令。普通类型命令是分配专有节点类型的命令,它允许您执行该类型的实例的任何可用的操作。它也可以修改现有实例上类型开放的任何属性。
connect 连接到指定主机和端口上的控制器。
connection-factory 定义连接工厂。
data-source 管理 datasource 子系统里的 JDBC 数据源配置。
deploy 部署用文件路径指定的应用程序或启用资料库里现有的被禁用的应用程序。如果不带参数执行,这个命令将列出全部现有的部署。
help 显示帮助信息。它可以用 --commands 参数为给定命令提供上下文敏感的内容。
history 显示内存里的 CLI 命令历史以及启用/禁用历史扩展的状态。它可以按需要用参数来清除、禁用和启用历史扩展。
jms-queue 在 messaging 子系统里定义一个 JMS 队列。
jms-topic 在 messaging 子系统里定义一个 JMS 主题。
ls 列出节点路径的内容。在默认情况下,终端窗口会用整屏以列显示结果。-l 参数将以每行一个名字显示结果。
pwd 显示当前工作节点的完整节点路径。
quit 终止命令行界面。
read-attribute 根据参数显示受管资源属性的值和描述。
read-operation 显示指定操作的描述,未指定则列出所有的操作。
undeploy 以应用程序的名称为参数运行可以卸载应用程序。它也可以通过参数运行从资料库删除应用程序。如无参数运行则输出所有现有的部署。
version 显示应用服务器版本和环境信息。
xa-data-source 管理 datasource 子系统里的 JDBC XA 数据源配置。

3.5.10. 管理 CLI 操作参考

开放管理 CLI 里的操作

管理 CLI 里的操作可以用 第 3.6.5 节 “用管理 CLI 显示操作名称” 里描述的 read-operation-names 操作开放。这些操作描述可以用 第 3.6.4 节 “用管理 CLI 显示操作描述” 里描述的 read-operation-descriptions 操作来开放。

Expand
表 3.4. 管理 CLI 操作
操作名称 描述
add-namespace 在 namespaces 属性的表里添加命名空间前缀映射。
add-schema-location 在 schema-locations 属性的表里添加模式位置 映射。
delete-snapshot 从 snapshots 目录删除服务器配置的快照。
full-replace-deployment 添加之前上传的部署内容到可用内容列表里,替换 runtime 里具有相同名称的现有内容,并从可用列表里删除替换的内容。进一步的信息请点击链接。
list-snapshots 列出保存在 snapshots 目录里的服务器配置的快照。
read-attribute 显示所选资源的属性的值。
read-children-names 显示给定类型的资源下的所有子资源的名称。
read-children-resources 显示给定类型的资源的所有子资源的信息。
read-children-types 显示所选资源下的所有子资源的类型名称。
read-config-as-xml 读取当前的配置并以 XML 格式显示。
read-operation-description 显示给定资源上的操作的细节。
read-operation-names 显示给定资源上的所有操作的名称。
read-resource 显示模型资源的属性值以及任何子资源的基本或完整的信息。
read-resource-description 显示资源属性的描述、子资源和操作的类型。
reload 关闭所有服务并重启来重载服务器。
remove-namespace 在 namespaces 属性的表里删除命名空间前缀映射。
remove-schema-location 在 schema-locations 属性的表里删除模式位置 映射。
replace-deployment 用新的内容替换 runtime 里的内容。新的内容必须已经上传到部署的内容资料库。
resolve-expression 接受表达式或可以解析为表达式的字符串的操作,并根据本地系统属性和环境变量进行解析。
resolve-internet-address 通过一系列接口解析标准找到本地主机上的 IP 地址,如果没有匹配的 IP 地址则运行失败。
server-set-restart-required 让服务器进入需要重启的模式
shutdown 通过调用 System.exit(0) 关闭服务器。
start-servers 启动受管域里配置的且当前没有运行的所有服务器。
stop-servers 停止当前运行在受管域里的所有服务器。
take-snapshot 创建服务器配置的快照并保存在 snapshots 目录。
upload-deployment-bytes 指定所包含的字节队列上的部署内容应该添加到部署内容资料库。请注意,这个操作没有指明内容应该部署至 runtime。
upload-deployment-stream 指定所包含的输入流索引上可用的部署内容应该添加到部署内容资料库。请注意,这个操作没有指明内容应该部署到 runtime。
upload-deployment-url 指定所包含的 URL 上可用的部署内容应该添加到部署内容资料库。请注意,这个操作没有指明内容应该部署至 runtime。
validate-address 检验操作的地址。
write-attribute 设置所选资源的属性的值。

3.6. 管理 CLI 操作

3.6.1. 用管理 CLI 显示资源属性

总结

read-attribute 操作是一个用来读取选定属性的当前 runtime 值的全局操作。它可以用来只开放用户设置的值而忽略任何默认或未定义的值。请求属性包括下列参数。

请求属性

name
获取所选资源下的值的属性的名称。
include-defaults
布尔型参数,可以设置为 false 来限制操作结果,只显示用户设置的属性并忽略默认的值。

过程 3.14. 显示所选属性的当前 Runtime 值

read-attribute 操作的优势是开放专有属性的当前 runtime 值的能力。用 read-resource 操作可获得类似的结果,但只能通过 include-runtime 请求属性,而且只作为该节点的所有可用资源的列表的一部分。read-attribute 操作用于细颗粒度的属性查询,如下例所示。

例 3.7. 运行 read-attribute 操作来开放公共的接口 IP。

如果您知道要开放的属性的名称,您可以使用 read-attribute 来获取当前 runtime 里的确切的值。
[standalone@localhost:9999 /] /interface=public:read-attribute(name=resolved-address)
{
    "outcome" => "success",
    "result" => "127.0.0.1"
}

resolved-address 属性是一个 runtime 值,所以不会显示在标准的 read-resource 操作的结果里。
[standalone@localhost:9999 /] /interface=public:read-resource                        
{
    "outcome" => "success",
    "result" => {
        "any" => undefined,
        "any-address" => undefined,
        "any-ipv4-address" => undefined,
        "any-ipv6-address" => undefined,
        "inet-address" => expression "${jboss.bind.address:127.0.0.1}",
        "link-local-address" => undefined,
        "loopback" => undefined,
        "loopback-address" => undefined,
        "multicast" => undefined,
        "name" => "public",
        "nic" => undefined,
        "nic-match" => undefined,
        "not" => undefined,
        "point-to-point" => undefined,
        "public-address" => undefined,
        "site-local-address" => undefined,
        "subnet-match" => undefined,
        "up" => undefined,
        "virtual" => undefined
    }
}

要显示 resolved-address 和其他 runtime 值,您必须使用 include-runtime 请求属性。
[standalone@localhost:9999 /] /interface=public:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "any" => undefined,
        "any-address" => undefined,
        "any-ipv4-address" => undefined,
        "any-ipv6-address" => undefined,
        "inet-address" => expression "${jboss.bind.address:127.0.0.1}",
        "link-local-address" => undefined,
        "loopback" => undefined,
        "loopback-address" => undefined,
        "multicast" => undefined,
        "name" => "public",
        "nic" => undefined,
        "nic-match" => undefined,
        "not" => undefined,
        "point-to-point" => undefined,
        "public-address" => undefined,
        "resolved-address" => "127.0.0.1",
        "site-local-address" => undefined,
        "subnet-match" => undefined,
        "up" => undefined,
        "virtual" => undefined
    }
}

结果

显示当前的 runtime 属性值。

3.6.2. 在管理 CLI 里显示活动用户

总结

whoami 操作是用于确定当前活动用户的全局操作。这个操作开放了用户名标识及它们分配的区。管理员可以用 whoami 操作来管理多个区上的多个用户帐号,或者跟踪具有多个终端会话和用户帐号的域实例上的活动用户。

过程 3.15. 在管理 CLI 里用 whoami 操作显示活动用户

  • 运行 whoami 操作

    在管理 CLI 里,请用 whoami 操作来显示活动的用户帐号。
    [standalone@localhost:9999 /] :whoami
    下面的例子使用了独立服务器实例里的 whoami 操作来显示活动用户 username,以及它所分配的 ManagementRealm 区。

    例 3.8. 在独立实例里使用 whoami

    [standalone@localhost:9999 /]:whoami
    {
        "outcome" => "success",
        "result" => {"identity" => {
            "username" => "username",
            "realm" => "ManagementRealm"
        }}
    }
    
    
结果

显示当前的活动用户帐号。

3.6.3. 在管理 CLI 里显示系统和服务器信息

过程 3.16. 在管理 CLI 里显示系统和服务器信息

  • 运行 version 命令

    在管理 CLI 里,输入 version 命令:
    [domain@localhost:9999 /] version
结果

显示应用服务器版本和环境信息。

3.6.4. 用管理 CLI 显示操作描述

过程 3.17. 在管理 CLI 里执行命令

  • 运行 read-operation-description 操作

    在管理 CLI 里,使用 read-operation-description 来显示操作信息。这个操作要求键-值格式的其他参数以指定要显示的操作。关于操作请求的详情,请参考 第 3.5.8 节 “在管理 CLI 里使用操作和命令”
    [standalone@localhost:9999 /]:read-operation-description(name=name-of-operation)

例 3.9. 显示 list-snapshots 操作的描述

下面的例子显示了描述 list-snapshots 操作的方法。
[standalone@localhost:9999 /] :read-operation-description(name=list-snapshots)
{
    "outcome" => "success",
    "result" => {
        "operation-name" => "list-snapshots",
        "description" => "Lists the snapshots",
        "request-properties" => {},
        "reply-properties" => {
            "type" => OBJECT,
            "value-type" => {
                "directory" => {
                    "type" => STRING,
                    "description" => "The directory where the snapshots are stored",
                    "expressions-allowed" => false,
                    "required" => true,
                    "nillable" => false,
                    "min-length" => 1L,
                    "max-length" => 2147483647L
                },
                "names" => {
                    "type" => LIST,
                    "description" => "The names of the snapshots within the snapshots directory",
                    "expressions-allowed" => false,
                    "required" => true,
                    "nillable" => false,
                    "value-type" => STRING
                }
            }
        },
        "access-constraints" => {"sensitive" => {"snapshots" => {"type" => "core"}}},
        "read-only" => false
    }
}
结果

显示所选操作的描述。

3.6.5. 用管理 CLI 显示操作名称

过程 3.18. 在管理 CLI 里执行命令

例 3.10. 用管理 CLI 显示操作名称

下面的例子显示了描述 read-operation-names 操作的方法。
[standalone@localhost:9999 /]:read-operation-names
{
    "outcome" => "success",
    "result" => [
        "add-namespace",
        "add-schema-location",
        "delete-snapshot",
        "full-replace-deployment",
        "list-snapshots",
        "read-attribute",
        "read-children-names",
        "read-children-resources",
        "read-children-types",
        "read-config-as-xml",
        "read-operation-description",
        "read-operation-names",
        "read-resource",
        "read-resource-description",
        "reload",
        "remove-namespace",
        "remove-schema-location",
        "replace-deployment",
        "resolve-expression",
        "resolve-internet-address",
        "server-set-restart-required",
        "shutdown",
        "take-snapshot",
        "undefine-attribute",
        "upload-deployment-bytes",
        "upload-deployment-stream",
        "upload-deployment-url",
        "validate-address",
        "validate-operation",
        "whoami",
        "write-attribute"
    ]
}
结果

显示可用的操作名称。

3.6.6. 用管理 CLI 显示可用资源

总结

read-resource 操作是用来读取资源值的全局操作。它可以用来开放当前节点或子节点额资源的基本或完整的信息,以及扩展或限制操作结果的作用域的请求属性。请求属性包含下列参数。

请求属性

recursive
是否递归地包含子资源的完整信息。
recursive-depth
应该包含子节点资源信息的深度。
proxies
是否在递归查询里包含远程资源。例如,包含域控制器查询里从主机控制器的主机级别资源。
include-runtime
是否在响应里包含 runtime 属性,如不是来自持久性配置的属性值。这个请求属性默认是 false。
include-defaults
这是一个 boolean 型的请求属性,它启用或禁用默认属性的读取。当设置为 false 时,只返回用户设置的属性,忽略了那些未定义的属性。

过程 3.19. 在管理 CLI 里执行命令

  1. 运行 read-resource 操作

    在管理 CLI 里,请用 read-resource 操作来显示可用的资源。
    [standalone@localhost:9999 /]:read-resource
    下面的例子展示了在独立服务器里如何使用 read-resource 操作来开放普通资源信息。结果类似于 standalone.xml 配置文件,显示系统资源、扩展、接口和为服务器实例安装和配置的子系统。它们可以进一步进行直接查询。

    例 3.11. 在根级别使用 read-resource 操作

    [standalone@localhost:9999 /]:read-resource
    {
        "outcome" => "success",
        "result" => {
            "deployment" => undefined,
            "deployment-overlay" => undefined,
            "management-major-version" => 1,
            "management-micro-version" => 0,
            "management-minor-version" => 4,
            "name" => "longgrass",
            "namespaces" => [],
            "product-name" => "EAP",
            "product-version" => "6.1.0.GA",
            "release-codename" => "Janus",
            "release-version" => "7.2.0.Final-redhat-3",
            "schema-locations" => [],
            "system-property" => undefined,
            "core-service" => {
                "management" => undefined,
                "service-container" => undefined,
                "server-environment" => undefined,
                "platform-mbean" => undefined
            },
            "extension" => {
                "org.jboss.as.clustering.infinispan" => undefined,
                "org.jboss.as.connector" => undefined,
                "org.jboss.as.deployment-scanner" => undefined,
                "org.jboss.as.ee" => undefined,
                "org.jboss.as.ejb3" => undefined,
                "org.jboss.as.jaxrs" => undefined,
                "org.jboss.as.jdr" => undefined,
                "org.jboss.as.jmx" => undefined,
                "org.jboss.as.jpa" => undefined,
                "org.jboss.as.jsf" => undefined,
                "org.jboss.as.logging" => undefined,
                "org.jboss.as.mail" => undefined,
                "org.jboss.as.naming" => undefined,
                "org.jboss.as.pojo" => undefined,
                "org.jboss.as.remoting" => undefined,
                "org.jboss.as.sar" => undefined,
                "org.jboss.as.security" => undefined,
                "org.jboss.as.threads" => undefined,
                "org.jboss.as.transactions" => undefined,
                "org.jboss.as.web" => undefined,
                "org.jboss.as.webservices" => undefined,
                "org.jboss.as.weld" => undefined
            },
            "interface" => {
                "management" => undefined,
                "public" => undefined,
                "unsecure" => undefined
            },
            "path" => {
                "jboss.server.temp.dir" => undefined,
                "user.home" => undefined,
                "jboss.server.base.dir" => undefined,
                "java.home" => undefined,
                "user.dir" => undefined,
                "jboss.server.data.dir" => undefined,
                "jboss.home.dir" => undefined,
                "jboss.server.log.dir" => undefined,
                "jboss.server.config.dir" => undefined,
                "jboss.controller.temp.dir" => undefined
            },
            "socket-binding-group" => {"standard-sockets" => undefined},
            "subsystem" => {
                "logging" => undefined,
                "datasources" => undefined,
                "deployment-scanner" => undefined,
                "ee" => undefined,
                "ejb3" => undefined,
                "infinispan" => undefined,
                "jaxrs" => undefined,
                "jca" => undefined,
                "jdr" => undefined,
                "jmx" => undefined,
                "jpa" => undefined,
                "jsf" => undefined,
                "mail" => undefined,
                "naming" => undefined,
                "pojo" => undefined,
                "remoting" => undefined,
                "resource-adapters" => undefined,
                "sar" => undefined,
                "security" => undefined,
                "threads" => undefined,
                "transactions" => undefined,
                "web" => undefined,
                "webservices" => undefined,
                "weld" => undefined
            }
        }
    }
    
    
  2. 针对子节点运行 read-resource 操作

    read-resource 操作可以查询根节点的子节点。操作的结构首先定义要开放的节点,然后附加这个操作来运行。
    [standalone@localhost:9999 /]/subsystem=web/connector=http:read-resource
    在下面的例子里,通过指引 read-resource 操作到专有的 Web 子系统节点来开放 Web 子系统组件的专有资源信息。

    例 3.12. 开放根结点的子节点资源

    [standalone@localhost:9999 /] /subsystem=web/connector=http:read-resource                      
    {
        "outcome" => "success",
        "result" => {
            "configuration" => undefined,
            "enable-lookups" => false,
            "enabled" => true,
            "executor" => undefined,
            "max-connections" => undefined,
            "max-post-size" => 2097152,
            "max-save-post-size" => 4096,
            "name" => "http",
            "protocol" => "HTTP/1.1",
            "proxy-name" => undefined,
            "proxy-port" => undefined,
            "redirect-port" => 443,
            "scheme" => "http",
            "secure" => false,
            "socket-binding" => "http",
            "ssl" => undefined,
            "virtual-server" => undefined
        }
    }
    
    
    相同的结果可以用 cd 命令进入子节点并直接运行 read-resource 操作获得。

    例 3.13. 通过修改目录开放子节点资源

    [standalone@localhost:9999 /] cd subsystem=web
    
    [standalone@localhost:9999 subsystem=web] cd connector=http
    
    [standalone@localhost:9999 connector=http] :read-resource
    {
        "outcome" => "success",
        "result" => {
            "configuration" => undefined,
            "enable-lookups" => false,
            "enabled" => true,
            "executor" => undefined,
            "max-connections" => undefined,
            "max-post-size" => 2097152,
            "max-save-post-size" => 4096,
            "name" => "http",
            "protocol" => "HTTP/1.1",
            "proxy-name" => undefined,
            "proxy-port" => undefined,
            "redirect-port" => 443,
            "scheme" => "http",
            "secure" => false,
            "socket-binding" => "http",
            "ssl" => undefined,
            "virtual-server" => undefined
        }
    }
    
    
  3. 使用 recursive 参数在结果里包含活动的属性值。

    recursive 参数可以用来开放所有属性的值,包括非持久性的值、在启动时传入的值或其他在 runtime 模型里活动的属性。
    [standalone@localhost:9999 /]/interface=public:read-resource(include-runtime=true)
    和之前的例子相比, include-runtime 请求属性会开放其他的活动属性,如发送的字节和 HTTP 连接器接收的字节。

    例 3.14. 用 include-runtime 参数开放其他活动的属性值。

    [standalone@localhost:9999 /] /subsystem=web/connector=http:read-resource(include-runtime=true)
    {
        "outcome" => "success",
        "result" => {
            "any" => undefined,
            "any-address" => undefined,
            "any-ipv4-address" => undefined,
            "any-ipv6-address" => undefined,
            "inet-address" => expression "${jboss.bind.address:127.0.0.1}",
            "link-local-address" => undefined,
            "loopback" => undefined,
            "loopback-address" => undefined,
            "multicast" => undefined,
            "name" => "public",
            "nic" => undefined,
            "nic-match" => undefined,
            "not" => undefined,
            "point-to-point" => undefined,
            "public-address" => undefined,
            "resolved-address" => "127.0.0.1",
            "site-local-address" => undefined,
            "subnet-match" => undefined,
            "up" => undefined,
            "virtual" => undefined
        }
    }
    
    

3.6.7. 用管理 CLI 显示可用资源的描述

过程 3.20. 在管理 CLI 里执行命令

  1. 运行 read-resource-description 操作

    在管理 CLI 里,使用 read-resource-description 来读取和显示可用资源。关于操作请求的详情,请参考 第 3.5.8 节 “在管理 CLI 里使用操作和命令”
    [standalone@localhost:9999 /]:read-resource-description
  2. 使用可选参数

    read-resource-description 操作允许使用其他参数。
    1. 使用 operations 参数来包含资源操作的描述。
      [standalone@localhost:9999 /]:read-resource-description(operations=true)
    2. 使用 inherited 参数可以包含或排除资源继承操作的描述。默认状态是 true。
      [standalone@localhost:9999 /]:read-resource-description(inherited=false)
    3. 使用 recursive 参数来包含子资源的递归描述。
      [standalone@localhost:9999 /]:read-resource-description(recursive=true)
    4. 使用 locale 参数来获取资源描述。如果为 null 则使用默认的 locale。
      [standalone@localhost:9999 /]:read-resource-description(locale=true)
结果

显示可用资源的描述。

3.6.8. 用管理 CLI 重载应用服务器

过程 3.21. 重载应用服务器

结果

关闭所有服务且再次启动 runtime 来完成服务器重载。管理 CLI 将自动重新连接。

3.6.9. 用管理 CLI 关闭应用服务器

过程 3.22. 关闭应用服务器

  • 运行 shutdown 操作

    • 在管理 CLI 里,使用 shutdown 操作通过 System.exit(0) 系统调用来关闭服务器。关于操作请求的详情,请参考 第 3.5.8 节 “在管理 CLI 里使用操作和命令”
      • 在独立模式下,请使用下列命令:
        [standalone@localhost:9999 /]:shutdown
      • 在域模式下,请使用下列命令及合适的主机名:
        [domain@localhost:9999 /]/host=master:shutdown
    • 要连接到附加的 CLI 实例并关闭服务器,请执行下列命令:
      jboss-cli.sh --connect command=:shutdown
      
    • 要连接到远程的 CLI 实例并关闭服务器,请执行下列命令:
      [disconnected /] connect IP_ADDRESS
      Connected to IP_ADDRESS:PORT_NUMBER
      [192.168.1.10:9999 /] :shutdown
      
      用实例的 IP 地址替换 IP_ADDRESS
结果

服务器被关闭。管理 CLI 将断开连接,因为 runtime 已是不可用的。

3.6.10. 使用管理 CLI 配置属性

总结

write-attribute 操作是用来写入或修改资源属性的全局操作。您可以使用这个操作来进行持久性修改并修改管理的服务器实例的配置设置。请求属性包含下列参数。

请求属性

name
需要设置值的所选资源属性的名称。
value
所选资源里属性的值。如果底层模型支持 null 值的话可以为 null。

过程 3.23. 使用管理 CLI 配置资源属性

  • 运行 write-attribute 操作

    在管理 CLI 里,使用 write-attribute 操作修改资源属性的值。这个擦作可以运行在资源的子节点或管理 CLI 的根节点上(指定完整资源路径)。

例 3.15. 用 write-attribute 操作禁用部署扫描器。

下面的例子使用了 write-attribute 操作来禁用部署扫描器。这个操作从根节点运行,使用 Tab Completion 来协助填充正确的资源路径。
[standalone@localhost:9999 /] /subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-enabled,value=false)
{"outcome" => "success"}

操作的结果可以直接用 read-attribute 操作确认。
[standalone@localhost:9999 /] /subsystem=deployment-scanner/scanner=default:read-attribute(name=scan-enabled)
{
    "outcome" => "success",
    "result" => false
}

read-resource 操作列出节点的所有可用资源属性可以确认资源。在下列例子里,这个特定的配置展示了 scan-enabled 属性被设置为 false
[standalone@localhost:9999 /] /subsystem=deployment-scanner/scanner=default:read-resource                                 
{
    "outcome" => "success",
    "result" => {
        "auto-deploy-exploded" => false,
        "auto-deploy-xml" => true,
        "auto-deploy-zipped" => true,
        "deployment-timeout" => 600,
        "path" => "deployments",
        "relative-to" => "jboss.server.base.dir",
        "scan-enabled" => false,
        "scan-interval" => 5000
    }
}

结果

更新了资源属性

3.7. 管理 CLI 命令历史

3.7.1. 使用管理 CLI 命令历史

应用服务器安装时会默认启用管理 CLI 的历史命令功能。这个历史记录既在活动的 CLI 会话的易变内存里保持一条记录,也附加内容在自动保存在用户的主目录的 .jboss-cli-history 日志文件上。这个历史记录文件默认是记录最多 500 条 CLI 命令。
history 命令自身将返回当前会话的历史记录,或用其他参数将禁用、启用或清除会话内存里的历史记录。管理 CLI 也可以通过键盘上的箭头来在命令和操作的历史记录里前进或后退。

3.7.2. 显示管理 CLI 命令历史

过程 3.24. 显示管理 CLI 命令历史

  • 运行 history 命令

    在管理 CLI 里,输入 history 命令:
    [standalone@localhost:9999 /] history
结果

在 CLI 启动或历史清除命令显示后保存在内存里的 CLI 命令历史。

3.7.3. 清除管理 CLI 命令历史

过程 3.25. 清除管理 CLI 命令历史

  • 运行 history --clear 命令

    在管理 CLI 里,输入 history --clear 命令:
    [standalone@localhost:9999 /] history --clear
结果

自 CLI 启动后记录的命令历史将从会话内存里删除。这些命令历史仍然保存在用户主目录的 .jboss-cli-history 文件里。

3.7.4. 禁用管理 CLI 命令历史

过程 3.26. 禁用管理 CLI 命令历史

  • 运行 history --disable 命令

    在管理 CLI 里,输入 history --disable 命令:
    [standalone@localhost:9999 /] history --disable
结果

CLI 里执行的命令不会记录在内存里或保存在用户主目录的 .jboss-cli-history 文件里。

3.7.5. 启用管理 CLI 命令历史

过程 3.27. 启用管理 CLI 命令历史

  • 运行 history --enable 命令

    在管理 CLI 里,输入 history --enable 命令:
    [standalone@localhost:9999 /] history --enable
结果

CLI 里执行的命令会记录在内存里并保存在用户主目录的 .jboss-cli-history 文件里。

3.8. 管理接口审计日志

3.8.1. 关于管理接口审计日志

启用审计日志后,通过管理 CLI 执行的操作将在审计日志记录。不管这些操作是否通过管理控制台、管理 CLI 还是自定义的接口执行,都会登记审计日志。日志记录可以输出到文件里或转发到 Syslog 服务器,也可以两者都进行。在默认情况下,审计日志是禁用的。
日志数据以 JSON 格式输出,并有几个配置选项可以影响日志里的操作及日志条目的格式。
在存储日志之前,格式器和处理程序会先处理日志条目。格式器指定日志条目的格式,而处理程序输出记录到指定的目的地。目前只有一个可用的格式器,它以 JSON 格式输出条目。

注意

审计日志只能通过管理 CLI 进行配置。

3.8.2. 从管理 CLI 里启用管理接口的审计日志

要在管理 CLI 启用审计日志,请使用下列命令。
/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)
审计日志是预配置输出到 EAP_HOME/standalone/data/audit-log.log 里的。

3.8.3. 关于管理接口的审计日志格式器

格式器指定日志条目的格式。
Expand
表 3.5. JSON 格式器字段
属性 描述
include-date 布尔值,它定义格式化日志记录是否包含时间戳。
date-separator 包含分隔日期和格式化日志信息的字符的字符串。如果 include-date=false 则被忽略。
date-format 用于时间戳的 java.text.SimpleDateFormat.可以时别的日期格式。如果 include-date=false 则被忽略。
compact 如果为 true,它将在一行里格式化 JSON 信息。因为仍有包含新行符的值,所以如果需要在同一行里容纳整个记录,可以设置 escape-new-lineescape-control-characterstrue
escape-control-characters 如果为 true,它将所有带有八进制 ASCII 字符的控制字符(带有十进制值 < 32 的 ASCII 条目)转义;例如新行将转义为 '#012'。如果它为 true,它将覆盖 escape-new-line=false
escape-new-line 如果为 true 会将所有带有八进制的 ASCII 代码的新行转义,例如 "#012"。

3.8.4. 关于管理接口的审计日志文件处理程序

文件处理程序通过参数来指定哪些日志记录输出到文件里。它还定义格式器、文件名和路径。
Expand
表 3.6. 文件处理程序的审计日志字段
属性 描述 只读的
formatter 用来格式化日志记录的 JSON 格式器的名称。 False
path 审计日志文件的路径。 False
relative-to 之前的命名路径的名称,或者系统提供的标准路径中的一个。如果提供了 relative-to,path 属性的值将作为这个属性指定的路径的相对路径对待。 False
failure-count 初始化处理程序前记录日志失败的次数。 True
max-failure-count 禁用这个处理程序前记录日志失败的最多次数。 False
disabled-due-to-failure true 表示如果登记日志失败则禁用处理程序。 True
Syslog 处理程序通过参数指定哪些审计日志条目被发送到 Syslog 服务器,特别是 Syslog 服务器侦听的的主机名和端口。
发送审计日志到 Syslog 服务器比本地文件或本地 Syslog 服务器提供了更安全的选项。您可以定义多个 Syslog 处理程序。
Syslog 服务器有不同的实现,所以并非所有设置都可应用到所有的 Syslog 服务器上。我们已用 rsyslog syslog 实现进行了测试。引用的 RFC 是:
  • http://www.ietf.org/rfc/rfc3164.txt
  • http://www.ietf.org/rfc/rfc5424.txt
  • http://www.ietf.org/rfc/rfc6587.txt
Expand
表 3.7. Syslog 处理程序字段
字段 描述 只读的值
formatter 用来格式化日志记录的格式器的名称。 False
failure-count 初始化处理程序前记录日志失败的次数。 True
max-failure-count 禁用这个处理程序前记录日志失败的最多次数。 False
disabled-due-to-failure True 表示如果登记日志失败则禁用处理程序。 True
syslog-format Syslog 格式:RFC-5424 或 RFC-3164. False
max-length 日志消息的最大长度(字节),包括头部信息。如果没有定义,syslog-format 为 RFC3164 时它默认为 1024 字节,而 syslog-format 为 RFC5424 时它默认为 2048 字节。 False.
truncate 如果消息长度超过最大字节数,是否要截短(包括头部信息)。如果为 false,消息将即兴分隔然后用相同的头部值来发送。 False

注意

如果要应用修改到受管域,请添加前缀 /host=HOST_NAME/core-service 命令上。

过程 3.28. 启用发送到 Syslog 服务器的日志

  1. 创建一个名为 msyslog 的 syslog 处理程序

    [standalone@localhost:9999 /]batch
    [standalone@localhost:9999 /]/core-service=management/access=audit/syslog-handler=mysyslog:add(formatter=json-formatter)
    [standalone@localhost:9999 /]/core-service=management/access=audit/syslog-handler=mysyslog/protocol=udp:add(host=localhost,port=514)
    [standalone@localhost:9999 /]run-batch
  2. 在 syslog 处理程序里添加一个引用。

    [standalone@localhost:9999 /]/core-service=management/access=audit/logger=audit-log/handler=mysyslog:add
结果

管理接口的审计日志登记在 syslog 服务器上。

3.8.7. 管理接口的审计日志选项

除了启用和禁用管理接口审计日志,还有其他可用的配置选项。

配置选项

log-boot
如果为 true,引导服务器时的管理操作将记录审计日志。如果为 false 则不会记录日志。默认为 false
log-read-only
如果为 true,所有的操作都将记录审计日志。如果为 false,只有修改了模型的操作会记录日志。默认为 false

3.8.8. 管理接口的审计日志字段

Expand
表 3.8. 管理接口的审计日志字段
字段名称 描述
type 它的值如果为 core,表示是一个管理操作;如果为 jmx,表示它来自 JMX 在系统(关于 JMX 子系统的审计日志请参考 JMX 子系统部分)。
r/o 如果操作没有修改管理模型则为 true,否则为 false
booting 如果操作是在引导过程中执行的则为 true,如果是在服务器启动并运行后执行的则为 false
version JBoss EAP 实例的版本号码。
user 已验证用户的用户名。如果和运行的服务器相同的主机为这个操作登记了日志,它将使用特殊的 $local 用户。
domainUUID 当所有操作从域控制器传播到服务器、从主机控制器和从主机控制器服务器时,链接所有操作的标识符。
access 它可以是下列值之一:NATIVE、HTTP、JMX。NATIVE - 操作通过原生管理接口进行,如 CLI。HTTP - 操作通过域 HTTP 接口进行,例如域控制台。JMX - 操作通过 JMX 子系统进行。关于如何配置 JMX 的审计日志,请参考 JMX 文档。
remote-address 执行这个操作的客户的地址。
success 如果操作成功则为 true,如果回滚则为 false
ops 被执行的操作。这是一个序列化到 JSON 的操作的列表。在引导时这是解析 XML 导致的所有操作。引导完成后,这个列表通常只包含单个条目。

第 4 章 用户管理

4.1. 用户创建

4.1.1. 为管理接口添加用户

概述

JBoss EAP 6 里的管理界面默认是设置了安全性的,因为一开始没有可用的用户帐号,除非你是用图形安装程序安装的。对于因简单配置错误而可能引起来自远程系统的攻击来说,这是一个预防措施。本地的非 HTTP 访问是受 SASL 机制保护的,就是当客户从 localhost 第一次连接时客户和服务器间都进行协商。

这个任务描述了如何创建初始的管理性用户,它可以使用基于 WEB 的管理控制台和管理 CLI 的远程实例来从远程系统上配置和管理 JBoss EAP 6。

注意

和 JBoss EAP 6 的 HTTP 通讯被当作是远程访问,即使这种通讯发生在本地主机。因此,你必须创建至少一个用户以能够使用管理控制台。如果你试图在添加用户前访问管理控制台,你将接收到一个错误,因为它在用户添加后才会被部署。

过程 4.1. 为远程管理界面创建初始管理性用户

  1. 调用 add-user.shadd-user.bat 脚本。

    进入 EAP_HOME/bin/ 目录。根据你的操作系统调用合适的脚本。
    红帽企业版 Linux
    [user@host bin]$ ./add-user.sh
    Microsoft Windows Server
    C:\bin>  add-user.bat
  2. 选择添加一个管理用户。

    点击 ENTER 选择默认选项 a 来添加一个管理用户。这个用户被添加到 ManagementRealm 并被授权通过基于 web 的管理控制台或基于命令行的管理 CLI 来执行管理操作。另外一个选项 b 则添加一个用户到 ApplicationRealm,且未提供特殊的权限。该区域(Realm)用于应用程序。
  3. 输入用户名和密码。

    遇到提示时输入用户名和密码,系统会提示您确认密码。
  4. 输入您的组信息

    添加用户所属的组或组群。如果用户属于多个组,请输入用逗号隔开的列表。如果不属于任何组,请留空。
  5. 获取信息并确认。

    系统会提示您确认信息。如果正确,请输入 yes
  6. 选择用户是否代表一个远程 JBoss EAP 6 服务器实例。

    除了管理员以外,偶尔需要在 ManagementRealm 里添加到 JBoss EAP 6 里的是代表其他 EAP 实例的用户,它需要通过验证作为成员加入到群集。下一个提示允许你指定所添加的用户。如果你选择 yes,你将得到一个 hashed secret 值,代表用户的密码,这将需要添加到不同的配置文件里。为了完成这个任务,在这里请回答 no
  7. 输入其他的用户。

    如果需要,重复刚才的过程你可以输入其他用户。你也可以在任何时候在运行系统里添加用户。不是选择默认的安全区,你需要添加用户到其他区以调整其授权过程。
  8. 非交互式地创建用户。

    通过在命令行传入参数,你可以非交互式地创建用户。我们不推荐在共享系统上使用这个方法,因为密码可以在日志或历史文件里看到。这个使用管理区域的命令的语法是:
    [user@host bin]$ ./add-user.sh usernamepassword
    要使用应用程序区域,请使用 -a 参数。
    [user@host bin]$ ./add-user.sh -a usernamepassword
  9. 通过 --silent 参数,你可以忽略 add-user 脚本的正常输出。这只有在指定了用户名密码且只使用了最小参数集时才适用。 而错误信息仍会被显示。
结果

你添加的任何用户都会在你指定的安全区里进行激活。ManagementRealm 区里活动的用户能够从远程系统里管理 JBoss EAP 6。

4.1.2. 传入参数到用户管理 add-user 脚本

您可以交互式地运行 add-user.shadd-user.bat 命令或将参数传入到命令行。本节描述了传入参数时可用的选项。
关于 add-user.shadd-user.bat 命令行的完整参数列表,请参考 第 4.1.3 节 “Add-user 命令行参数”
关于如何指定其他属性文件和位置,请参考 第 4.1.4 节 “指定用户管理信息的替代属性文件”
关于演示如何传递参数到 add-user.shadd-user.bat 命令行的示例,请参考 第 4.1.5 节 “Add-user 脚本命令行示例”

4.1.3. Add-user 命令行参数

下表描述了 add-user.shadd-user.bat 命令的可用参数。
Expand
表 4.1. Add-user 命令行参数
命令行参数 参数值 描述
-a
N/A
这个参数指定在应用程序区里创建用户。如果忽略,默认是在管理区里创建用户。
-dc
DOMAIN_CONFIGURATION_DIRECTORY
这个参数指定了包含属性文件的域配置目录。如果忽略,默认的目录是 EAP_HOME/domain/configuration/
-sc
SERVER_CONFIGURATION_DIRECTORY
这个参数指定了包含属性文件的其他独立服务器配置目录。如果忽略,默认的目录是 EAP_HOME/standalone/configuration/
-up
--user-properties
USER_PROPERTIES_FILE
这个参数指定其他用户属性文件的名称。它可以是一个绝对路径,也可以和 -sc-dc 参数一起来指定其他配置的目录。
-g
--group
GROUP_LIST
分配给这个用户的用逗号隔开的组的列表。
-gp
--group-properties
GROUP_PROPERTIES_FILE
这个参数指定其他组属性文件的名称。它可以是一个绝对路径,也可以和 -sc-dc 参数一起来指定其他配置的目录。
-p
--password
PASSWORD
用户的密码。密码必须满足下列要求:
  • 它不能和用户名相同。
  • 它必须包含至少 8 个字符。
  • 它必须包含至少一个字母数字字符。
  • 它必须包含至少一个数字。
  • 它必须包含至少一个非字母数字字符。
-u
--user
USER_NAME
用户的名称。
-r
--realm
REALM_NAME
用来设置管理接口安全性的区的名称。如果忽略,默认是 "ManagementRealm"。
-s
--silent
N/A
运行 add-user 脚本且不输出到控制台。
-h
--help
N/A
显示 add-user 脚本的用法。

4.1.4. 指定用户管理信息的替代属性文件

概述

在默认情况下,用 add-user.shadd-user.bat 创建的用户和角色信息都保存在服务器配置目录下的属性文件里。服务器配置信息保存在 EAP_HOME/standalone/configuration/ 目录而域配置信息保存在 EAP_HOME/domain/configuration/ 目录。本节将描述如何覆盖默认的文件名称和位置。

过程 4.2. 指定替代属性文件

    • 要指定服务器配置的替代目录,请使用 -sc 参数。这个参数指定了包含服务器配置属性文件的替代目录。
    • 要为域配置指定替代目录,,请使用 -dc 参数。这个参数指定了包含域配置属性文件的替代目录。
    • 要指定替代的用户配置属性文件,请使用 -up--user-properties 参数。它可以是绝对路径,也可以和 -sc-dc 参数一起使用来指定替代的配置目录。
    • 要指定替代的组配置属性文件,请使用 -gp--group-properties 参数。它可以是绝对路径,也可以和 -sc-dc 参数一起使用来指定替代的配置目录。

注意

add-user 命令旨在操作现有的属性文件。命令行里指定任何替代属性文件都必须存在,否则您将看到下列错误:
JBAS015234: No appusers.properties files found
关于命令参数的更多信息,请参考 第 4.1.3 节 “Add-user 命令行参数”
关于 add-user 命令的示例,请参考 第 4.1.5 节 “Add-user 脚本命令行示例”

4.1.5. Add-user 脚本命令行示例

下面的例子演示了如何传递参数到 add-user.shadd-user.bat 命令。除非另有注明,这些命令假定是使用独立服务器配置的。

例 4.1. 创建属于使用默认属性文件的单个组的用户。

EAP_HOME/bin/add-user.sh -a -u 'appuser1' -p 'password1!' -g 'guest'
上面的命令产生下列结果。
  • 用户 appuser1 被添加到保存用户信息的下列默认属性文件里。
    EAP_HOME/standalone/configuration/application-users.properties
    EAP_HOME/domain/configuration/application-users.properties
  • 用户 appuser1 和组 guest 被添加到保存组信息的默认属性文件里。
    EAP_HOME/standalone/configuration/application-roles.properties
    EAP_HOME/domain/configuration/application-roles.properties

例 4.2. 创建属于使用默认属性文件的多个组的用户。

EAP_HOME/bin/add-user.sh -a -u 'appuser1' -p 'password1!' -g 'guest,app1group,app2group'
上面的命令产生下列结果。
  • 用户 appuser1 被添加到保存用户信息的下列默认属性文件里。
    EAP_HOME/standalone/configuration/application-users.properties
    EAP_HOME/domain/configuration/application-users.properties
  • 用户 appuser1 和组 guestapp1groupapp2group被添加到保存组信息的默认属性文件里。
    EAP_HOME/standalone/configuration/application-roles.properties
    EAP_HOME/domain/configuration/application-roles.properties

例 4.3. 在使用默认属性文件的默认区里创建带有管理权限的用户。

EAP_HOME/bin/add-user.sh -u 'adminuser1' -p 'password1!' -g 'admin'
上面的命令产生下列结果。
  • 用户 adminuser1 被添加到保存用户信息的下列默认属性文件里。
    EAP_HOME/standalone/configuration/mgmt-users.properties
    EAP_HOME/domain/configuration/mgmt-users.properties
  • 用户 adminuser1 和组 admin 被添加到保存组信息的默认属性文件里。
    EAP_HOME/standalone/configuration/mgmt-groups.properties
    EAP_HOME/domain/configuration/mgmt-groups.properties

例 4.4. 创建属于用替代属性文件保存信息的单个组的用户。

EAP_HOME/bin/add-user.sh -a -u appuser1 -p password1! -g app1group -sc /home/someusername/userconfigs/ -up appusers.properties -gp appgroups.properties 
上面的命令产生下列结果。
  • 我们添加了用户 appuser1 到下列属性文件里,它现在是保存用户信息的默认文件。
    /home/someusername/userconfigs/appusers.properties
  • 我们添加了用户 appuser1 和组 app1group 到下列属性文件里,它现在是保存组信息的默认文件。
    /home/someusername/userconfigs/appgroups.properties

第 5 章 网络和端口配置

5.1. 接口

5.1.1. 关于接口

应用服务器在整个配置里都使用命名接口引用。这让配置可以用逻辑名称引用单独的接口声明,而不是每次都使用整个接口细节。逻辑名称的使用也保持了组引用和命名接口的一致性,而受管域上的服务器实例可能包含多个主机上不同的接口细节。使用这个方法,每个服务器实例可能对应逻辑名称组,它可以将接口组作为整体进行管理。
网络接口是通过指定逻辑名和物理接口的选择标准来声明的。应用服务器附带有用于管理及公共接口名称的默认配置。在这个配置里,公共接口组的目的是用于和应用程序相关的网络通讯,如 Web 或 Messaging。管理接口组的目的是用于管理层要求的所有组件和服务,包括 HTTP 管理端点。接口名自身是仅作为建议来提供的,任何组的名称都可以按照需要进行替换和创建。
domain.xml, host.xmlstandalone.xml 都包含了接口声明。声明标准可以引用通配符地址或指定接口或地址必须具有来进行有效匹配的一个或多个特征。下面的例子展示了接口声明的多个可能的配置,它们通常是在 standalone.xmlhost.xml 配置文件里定义的。这允许任何远程主机组维护自己所专有的接口属性,且仍然允许对域控制器里的 domain.xml 配置文件里任何接口组的引用。
第一个例子展示了为 managementpublic 相对名称组指定的专有的 inet-address 值。

例 5.1. 用 inet-address 值创建的接口组

<interfaces>
  <interface name="management">
   <inet-address value="127.0.0.1"/>
  </interface>
  <interface name="public">
   <inet-address value="127.0.0.1"/>
  </interface>
</interfaces>


在下面的例子里,全局接口组使用了 any-address 元素来声明通配符地址。

例 5.2. 用通配符声明创建的全局组

<interface name="global">
   <!-- Use the wild-card address -->
   <any-address/>
</interface>


下面的例子声明了名为 external 的相对组下的一个网络接口卡。

例 5.3. 用 NIC 值创建的外部组

        
<interface name="external">
   <nic name="eth0"/>
</interface>


在下面的例子里,根据专有需求,声明作为默认组创建。在这个实例里,其他元素的特征为接口设置了条件以进行有效的匹配。这允许每个专有接口声明组的创建,且能够以当前模式引用它们,从而减少了跨多个服务器实例的配置和管理。

例 5.4. 用专有条件值创建的默认组

<interface name="default">
   <!-- Match any interface/address on the right subnet if it's
        up, supports multicast, and isn't point-to-point -->
   <subnet-match value="192.168.0.0/16"/>
   <up/>
   <multicast/>
   <not>
      <point-to-point/>
   </not>
</interface>


虽然接口声明可以在源配置文件里创建和编辑,管理 CLI 和管理控制台为配置的修改提供了安全的、可控和持久性的环境。

5.1.2. 配置接口

standalone.xmlhost.xml 配置文件里默认的接口配置通常提供三个带有相对接口令牌的命名接口。您可以使用管理控制台或管理 CLI 来配置下表列出的其他属性和值。你也可以按需要用专有值替换相对的接口绑定。请注意,如果您这样做,您将无法在运行时传入接口值,因为 -b 选项只能覆盖相对值。

例 5.5. 默认的接口配置

        <interfaces>
            <interface name="management">
                <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
            </interface>
            <interface name="public">
                <inet-address value="${jboss.bind.address:127.0.0.1}"/>
            </interface>
            <interface name="unsecure">
                <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"/>
            </interface>
        </interfaces>

Expand
表 5.1. 接口属性和值
接口元素 描述
any 地址排斥类型的空元素,用于约束选择标准。
any-address 空元素表示使用这个接口的套接字应该绑定到通配符地址。除非设置 java.net.preferIpV4Stack 系统属性为 true,否则 IPv6 将使用通配符地址(::),而 IPv4 将使用通配符地址(0.0.0.0)。如果套接字绑定到双栈主机上的任何本地 IPv6 地址,它可以接受 IPv6 及 IPv4 数据。如果绑定到任何的本地 IPv4 地址,它就只能接受 IPv4 数据。
any-ipv4-address 空元素表示使用这个接口的套接字应该绑定到 IPv4 通配符地址(0.0.0.0)。
any-ipv6-address 空元素表示使用这个接口的套接字应该绑定到 IPv6 通配符地址(::)。
inet-address 请输入 IPv6 格式的 IP 地址或者用小数点隔开的 IPv4 地址,或者可以解析为 IP 地址的主机名。
link-local-address 空元素表示接口的部分选择标准应该是或不是和 link-local 关联的地址。
loopback 空元素表示接口的部分选择标准应该是或不是 loopback 接口。
loopback-address 可能实际上不会在主机的 loopback 接口上配置的 loopback 地址。和 inet-addressType 不同的是,即使没有找到和 IP 地址相关的 NIC,给定的值也将被使用。
multicast 空元素表示接口的部分选择标准应该支持或不支持多点传送。
nic 网络接口的名称(如 eth0, eth1, lo) 。
nic-match 常规表达式,表示主机上可以映射可接受的接口的网络接口的名称。
not 地址排斥类型的空元素,用于约束选择标准。
point-to-point 空元素表示接口的部分选择标准是是否为 point-to-point 接口。
public-address 空元素表示接口的部分选择标准应该有或没有公共路由的地址。
site-local-address 空元素表示接口的部分选择标准应该是或不是和 site-local 关联的地址。
subnet-match 网络 IP 地址和地址的网络前缀的位数,以斜杠和数字表示;如 "192.168.0.0/16"。
up 空元素表示接口的部分选择标准应该是或不是正在运行。
virtual 空元素表示接口的部分选择标准应该是或不是虚拟接口。
  • 配置接口属性

    请选择管理 CLI 或管理控制台来按需要配置接口属性。
    • 用管理 CLI 配置接口属性

      使用管理 CLI 来添加新的接口并编写新的接口属性的值。
      1. 添加新的接口

        使用 add 操作来创建新的接口。您可以在管理 CLI 会话的根目录里运行这个命令,下面的例子创建了一个名为 interfacename 的接口,它将 inet-address 声明为 12.0.0.2
        /interface=interfacename/:add(inet-address=12.0.0.2)
      2. 编辑接口属性

        使用 write 操作来编写新的属性的值。您可以使用 tab completion 来帮助输入并提示所有可用的值。下面的例子将 inet-address 的值更新为 12.0.0.8
        /interface=interfacename/:write(inet-address=12.0.0.8)
      3. 编辑接口属性

        通过 include-runtime=true 参数运行 read-resource 操作来确认值已修改以开放服务器模型里所有当前的值。
        [standalone@localhost:9999 interface=public] :read-resource(include-runtime=true)
    • 用管理控制台配置接口属性

      使用管理控制台来添加新的接口并编写新的接口属性的值。
      1. 登录到管理控制台。

        登录到受管域或独立服务器实例的管理控制台。
      2. 如果您使用了受管域,请选择正确的配置集。

        选择右上角的 Profiles 标签,然后从下一屏幕的 Profile 里选择正确的配置集。
      3. 从导航菜单里选择 Interfaces 条目。

        从导航菜单里选择 Interfaces 菜单条目。
      4. 添加新的接口

        1. 点击 Add 按钮。
        2. 输入 NameInet AddressAddress Wildcard 的值。
        3. 点击“Save”完成。
      5. 编辑接口属性

        1. 选择要编辑的接口并点击 Edit 按钮。
        2. 输入 NameInet AddressAddress Wildcard 的值。
        3. 点击“Save”完成。

5.2. 套接字绑定组

5.2.1. 关于套接字绑定组

套接字绑定和绑定组允许您定义网络接口及它们和 JBoss EAP 6 配置要求的网络接口的关系。
套接字绑定是用于套接字的命名配置。这些命名配置的声明可以在 domain.xmlstandalone.xml 配置文件里找到。配置的其他部分可以通过逻辑名引用这些套接字,而无需包含套接字配置的完整细节。这允许您引用不同主机上可能不同的相对套接字配置。
套接字绑定是通过套接字组来收集的。套接字绑定组是按照逻辑名称分组的套接字绑定声明的集合。然后这个命名组可以在整个配置里进行引用。独立服务器配置只包含一个这样的组,而受管域实例则可以包含多个组。您可以在受管域里为每个服务器组创建一个套接字绑定组,或者在多个服务器组间分享套接字绑定组。
在配置受管域的服务器组时,命名组允许对特定的套接字绑定组使用简化的引用。另外一个通常的用途是对同一个系统上的多个独立服务器实例的配置和管理。下面的例子分别展示了独立和域实例的配置文件里的默认套接字绑定组。

例 5.6. 独立配置的默认套接字绑定

standalone.xml 配置文件里的默认套接字绑定组是按照 standard-sockets 分组的。public 接口也通过相同的逻辑引用方法引用了这个组。
   
<socket-binding-group name="standard-sockets" default-interface="public">
    <socket-binding name="http" port="8080"/>
    <socket-binding name="https" port="8443"/>
    <socket-binding name="jacorb" port="3528"/>
    <socket-binding name="jacorb-ssl" port="3529"/>
    <socket-binding name="jmx-connector-registry" port="1090" interface="management"/>
    <socket-binding name="jmx-connector-server" port="1091" interface="management"/>
    <socket-binding name="jndi" port="1099"/>
    <socket-binding name="messaging" port="5445"/>
    <socket-binding name="messaging-throughput" port="5455"/>
    <socket-binding name="osgi-http" port="8090" interface="management"/>
    <socket-binding name="remoting" port="4447"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
</socket-binding-group>

例 5.7. 域配置的默认套接字绑定

domain.xml 配置文件里的默认套接字绑定组包含了四个组:standard-socketsha-socketsfull-socketsfull-ha-sockets。这些组也被名为 public 的接口所引用。
<socket-binding-groups>
    <socket-binding-group name="standard-sockets" default-interface="public">
        <!-- Needed for server groups using the 'default' profile  -->
        <socket-binding name="ajp" port="8009"/>
        <socket-binding name="http" port="8080"/>
        <socket-binding name="https" port="8443"/>
        <socket-binding name="osgi-http" interface="management" port="8090"/>
        <socket-binding name="remoting" port="4447"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>
    <socket-binding-group name="ha-sockets" default-interface="public">
        <!-- Needed for server groups using the 'ha' profile  -->
        <socket-binding name="ajp" port="8009"/>
        <socket-binding name="http" port="8080"/>
        <socket-binding name="https" port="8443"/>
        <socket-binding name="jgroups-mping" port="0" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45700"/>
        <socket-binding name="jgroups-tcp" port="7600"/>
        <socket-binding name="jgroups-tcp-fd" port="57600"/>
        <socket-binding name="jgroups-udp" port="55200" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45688"/>
        <socket-binding name="jgroups-udp-fd" port="54200"/>
        <socket-binding name="modcluster" port="0" multicast-address="224.0.1.105" multicast-port="23364"/>
        <socket-binding name="osgi-http" interface="management" port="8090"/>
        <socket-binding name="remoting" port="4447"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>
    <socket-binding-group name="full-sockets" default-interface="public">
        <!-- Needed for server groups using the 'full' profile  -->
        <socket-binding name="ajp" port="8009"/>
        <socket-binding name="http" port="8080"/>
        <socket-binding name="https" port="8443"/>
        <socket-binding name="jacorb" interface="unsecure" port="3528"/>
        <socket-binding name="jacorb-ssl" interface="unsecure" port="3529"/>
        <socket-binding name="messaging" port="5445"/>
        <socket-binding name="messaging-group" port="0" multicast-address="${jboss.messaging.group.address:231.7.7.7}" multicast-port="${jboss.messaging.group.port:9876}"/>
        <socket-binding name="messaging-throughput" port="5455"/>
        <socket-binding name="osgi-http" interface="management" port="8090"/>
        <socket-binding name="remoting" port="4447"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>
    <socket-binding-group name="full-ha-sockets" default-interface="public">
        <!-- Needed for server groups using the 'full-ha' profile  -->
        <socket-binding name="ajp" port="8009"/>
        <socket-binding name="http" port="8080"/>
        <socket-binding name="https" port="8443"/>
        <socket-binding name="jacorb" interface="unsecure" port="3528"/>
        <socket-binding name="jacorb-ssl" interface="unsecure" port="3529"/>
        <socket-binding name="jgroups-mping" port="0" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45700"/>
        <socket-binding name="jgroups-tcp" port="7600"/>
        <socket-binding name="jgroups-tcp-fd" port="57600"/>
        <socket-binding name="jgroups-udp" port="55200" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45688"/>
        <socket-binding name="jgroups-udp-fd" port="54200"/>
        <socket-binding name="messaging" port="5445"/>
        <socket-binding name="messaging-group" port="0" multicast-address="${jboss.messaging.group.address:231.7.7.7}" multicast-port="${jboss.messaging.group.port:9876}"/>
        <socket-binding name="messaging-throughput" port="5455"/>
        <socket-binding name="modcluster" port="0" multicast-address="224.0.1.105" multicast-port="23364"/>
        <socket-binding name="osgi-http" interface="management" port="8090"/>
        <socket-binding name="remoting" port="4447"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>
</socket-binding-groups>

套接字绑定实例可以在应用服务器目录下的 standalone.xmldomain.xml 文件里创建和编辑。我们推荐的管理绑定的方法是使用管理控制台或管理 CLI。使用管理控制台的优势包括图形化的用户界面,在 General Configuration 部分里有专门的 Socket Binding Group 屏幕。管理 CLI 提供 API 和基于命令行的批处理工作流程,并可以对应用服务器配置的更高和更低级别使用脚本。两种界面都可以持久化修改或者保存修改到服务器配置文件里。

5.2.2. 配置套接字绑定

套接字绑定可以在唯一的套接字绑定组里定义。独立服务器包含一个 standard-sockets 组,且无法创建更多的组。相反,您可以创建替代的独立服务器配置文件。对于受管域,您可以创建多个套接字绑定组并按需要配置它们包含的套接字绑定。下表展示了每个套接字绑定的可用属性。
Expand
表 5.2. 套接字绑定属性
组件 描述 角色
名称 应该用在配置里其他位置的套接字配置的逻辑名。 要求的
端口 基于这个配置的套接字应该绑定的基础端口。请注意,您可以通过应用于所有端口的增量或减量来配置服务器以覆盖这个基础值。 要求的
接口 基于这个配置的套接字应该绑定的接口的逻辑名。如果没有定义,将会使用附带的套接字绑定组里 "default-interface" 属性的值。 自选的
多点传送地址 如果套接字用于多点传送,要使用的多点传送地址。 自选的
多点传送接口 绑定到会话的生命周期。会话作用域处于请求长度和会话之间,由应用程序控制。 自选的
固定端口 如果上面的上下文没有满足您的需要,您可以定义自定义作用域。 自选的
  • 配置套接字绑定组里的套接字绑定

    请选择管理 CLI 或管理控制台来按需要配置套接字绑定。
    • 使用管理 CLI 配置套接字绑定

      使用管理 CLI 配置套接字绑定。
      1. 添加新的套接字绑定

        如果有需要,请使用 add 操作来创建新的地址设置。您可以在管理 CLI 会话的根目录里运行这个命令,下面的例子创建了一个名为 newsocket 的套接字绑定,它的 port 属性声明为 1234。这些例子适用于独立服务器和受管域的 standard-sockets 套接字绑定组。
        [domain@localhost:9999 /] /socket-binding-group=standard-sockets/socket-binding=newsocket/:add(port=1234)
      2. 编辑 Pattern 属性

        使用 write-attribute 操作来编写新的属性的值。您可以使用 tab completion 来帮助输入并提示所有可用的值。下面的例子将 port 的值更新为 2020
        [domain@localhost:9999 /] /socket-binding-group=standard-sockets/socket-binding=newsocket/:write-attribute(name=port,value=2020)
      3. 确认 Pattern 属性

        通过 include-runtime=true 参数运行 read-resource 操作来确认值已修改以开放服务器模型里所有当前的值。
        [domain@localhost:9999 /] /socket-binding-group=standard-sockets/socket-binding=newsocket/:read-resource
    • 使用管理控制台配置套接字绑定

      使用管理控制台配置套接字绑定。
      1. 登录到管理控制台。

        登录到受管域或独立服务器的管理控制台。
      2. 选择 Profile tab

        从控制台的右上角选择 Profiles 标签页。
      3. 从导航菜单里选择 Socket Binding 菜单条目。

        从导航菜单里选择 Socket Binding 条目。如果您使用受管域,请选择 Socket Binding Groups 菜单里的组。
      4. 添加新的套接字绑定

        1. 点击 Add 按钮。
        2. 输入 Name, PortBinding Group 的值。
        3. 点击“Save”完成。
      5. 编辑接口属性

        1. 选择要编辑的套接字绑定并点击 Edit 按钮。
        2. 输入 Name, InterfacePort 的值。
        3. 点击“Save”完成。

5.2.3. JBoss EAP 6 使用的网络端口

JBoss EAP 6 的默认配置使用的端口取决于下列因素:
  • 你的服务器组是否使用了默认的套接字绑定组,或者自定义的套接字绑定组。
  • 单独部署的要求。

注意

你可以配置一个数字的端口偏移量,以减缓当在同一个服务服务器上运行多个服务器时端口冲突。如果你的服务器使用了数字的端口偏移量,在它的服务器组的套接字绑定组的默认端口上添加偏移量。例如,如果套接字绑定组的 HTTP 端口是 8080,而你的服务器使用了端口偏移量为 100,那么它的 HTTP 端口是 8180。
除非额外指定,这个端口将使用 TCP 协议。

默认的套接字绑定组

  • full-ha-sockets
  • full-sockets
  • ha-sockets
  • standard-sockets
Expand
表 5.3. 默认的套接字绑定组的引用
名称 端口 多点传送端口 描述 full-ha-sockets full-sockets ha-socket standard-socket
ajp 8009 Apache JServ 协议,用于 HTTP 群集和负载平衡。
http 8080 用于已部署应用程序的默认端口。
https 8443 已部署的应用程序和客户间的用 SSL 加密的连接。
jacorb 3528 用于 JTS 事务的 CORBA 服务和其他依赖于 ORB 的服务。
jacorb-ssl 3529 SSL 加密的 CORBA 服务。
jgroups-diagnostics 7500 多点传送。用于 HA 群集里的 Peer 发现。不能使用管理界面进行配置。
jgroups-mping 45700 多点传送。用于在 HA 群集里发现初始成员资格。
jgroups-tcp 7600 HA 群集里使用 TCP 的多点传送 Peer 发现。
jgroups-tcp-fd 57600 用于 TCP 上的 HA 失败检测。
jgroups-udp 55200 45688 HA 群集里使用 UDP 的多点传送 Peer 发现。
jgroups-udp-fd 54200 用于 UDP 上的 HA 失败检测。
messaging 5445 JMS 服务。
messaging-group 被 HornetQ JMS 广播和发现组引用。
messaging-throughput 5455 JMS remoting 所使用的。
mod_cluster 23364 用于 JBoss EAP 6 和 HTTP 加载平衡器之间通讯的多点传送端口。
osgi-http 8090 由使用 OSGi 子系统的内部组件使用。不能通过管理界面进行配置。
remoting 4447 用于远程 EJB 调用。
txn-recovery-environment 4712 JTA 事务恢复管理者。
txn-status-manager 4713 JTA / JTS 事务管理者。
管理端口

除了套接字绑定组,每个主机控制台都打开另外两个端口用于管理:

  • 9990 - Web 管理控制台的端口
  • 9999 - 管理控制台和 API 使用的端口

5.2.4. 关于套接字绑定组的端口偏移

端口偏移是添加到服务器的套接字组给定的端口值的数字偏移量。这允许单个服务器继承服务器组的套接字绑定,并用偏移量来确保它和组里的其他服务器不冲突。例如,如果套接字绑定组的 HTTP 端口是 8080,而你的服务器使用了端口偏移量为 100,那么它的 HTTP 端口是 8180。

5.2.5. 配置端口偏移

  • 配置端口偏移

    选择管理 CLI 或管理控制台来配置您的端口偏移。
    • 使用管理 CLI 配置端口偏移

      使用管理 CLI 来配置端口偏移。
      1. 编辑端口偏移

        使用 write-attribute 操作来为端口偏移属性编写新的值。下面的例子更新了 server-twosocket-binding-port-offset 值为 250。这个服务器是默认本地主机组的成员。为使改动生效,服务器需要重启。
        [domain@localhost:9999 /] /host=master/server-config=server-two/:write-attribute(name=socket-binding-port-offset,value=250)
      2. 确认端口偏移属性

        运行 read-resource 操作并使用 include-runtime=true 参数来开放服务器模型里当前所有的值,从而确认修改。
        [domain@localhost:9999 /] /host=master/server-config=server-two/:read-resource(include-runtime=true)
    • 使用管理控制台来配置端口偏移

      使用管理控制台来配置端口偏移。
      1. 登录到管理控制台。

        登录到您的受管域的管理控制台。
      2. 选择 Hosts 标签页

        选择右上角的 Hosts 标签页。
      3. 编辑端口偏移属性

        1. 选择 Configuration Name 里的服务器并点击 Edit 按钮。
        2. Port Offset 字段里输入想要的值。
        3. 点击 Save 按钮完成。

5.3. IPv6

5.3.1. 配置 IPv6 网络的 JVM Stack 首选项

总结
本节涵盖为 JBoss EAP 6 安装启用 IPv6 网络。

过程 5.1. 禁用 IPv4 Stack Java 属性

  1. 打开相关的安装文件:
    • 对于独立服务器:

      打开 EAP_HOME/bin/standalone.conf
    • 对于受管域:

      打开 EAP_HOME/bin/domain.conf
  2. 修改 IPv4 Stack Java 属性为 false:
    -Djava.net.preferIPv4Stack=false
    例如:
    # Specify options to pass to the Java VM.
    #
    if [ "x$JAVA_OPTS" = "x" ]; then
       JAVA_OPTS="-Xms64m -Xmx512m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=false 
       -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 
       -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.net.preferIPv6Addresses=true"
    fi
    

5.3.2. 配置 IPv6 网络的接口声明

总结

遵循下列步骤来配置 IPv6 的接口 inet 地址:

过程 5.2. 配置 IPv6 网络的接口

  1. 请选择控制台右上角的 Profile 标签页。
  2. 选择 General Configuration 下的 Interfaces 选项。
  3. 选择要配置的命名网络接口。
  4. 点击 Edit 按钮。
  5. 设置 inet 地址为:
    ${jboss.bind.address.management:[ADDRESS]}
  6. 点击 Save 按钮来保存修改。
  7. 重启服务器来应用这些修改。

5.3.3. 配置 IPv6 地址的 JVM Stack 首选项

总结
本节涵盖通过配置文件配置 JBoss EAP 6 安装首选 IPv6 地址。

过程 5.3. 配置 JBoss EAP 6 安装首选 IPv6 地址

  1. 打开相关的安装文件:
    • 对于独立服务器:

      打开 EAP_HOME/bin/standalone.conf
    • 对于受管域:

      打开 EAP_HOME/bin/domain.conf
  2. 附加下列 Java 属性到 Java VM 选项:
    -Djava.net.preferIPv6Addresses=true
    例如:
    # Specify options to pass to the Java VM.
    #
    if [ "x$JAVA_OPTS" = "x" ]; then
       JAVA_OPTS="-Xms64m -Xmx512m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=false 
       -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 
       -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.net.preferIPv6Addresses=true"
    fi
    

第 6 章 数据源管理

6.1. 简介

6.1.1. 关于 JDBC

JDBC API 是定义 Java 应用程序如何访问数据库的标准。应用程序配置引用 JDBC 驱动的数据源。然后可以再次针对驱动而不是数据库编写应用程序代码。驱动将代码转换为数据库语言。这表示如果安装了正确的驱动,应用程序就可以使用受支持的数据库了。
JDBC 4.0 规格是在这里定义的:http://jcp.org/en/jsr/detail?id=221
要开始使用 JDBC 和数据源,请参考 JBoss EAP 6 的《管理和配置指南》里的《JDBC 驱动》章节。

6.1.2. JBoss EAP 6 支持的数据库

关于 JBoss EAP 6 支持的兼容 JDBC 的数据库列表,请参考:https://access.redhat.com/site/articles/111663

6.1.3. 数据源的类型

两种常用的资源类型是非 XA 数据源XA 数据源
非 XA 数据源用于不使用事务的应用程序,或者以单个数据库使用事务的应用程序。
XA 数据源用于事务分布在多个数据库的应用程序。XA 数据源会导致额外的负荷。
当你在管理控制台或管理 CLI 里创建数据源时,你可以指定它的类型。

6.1.4. 数据源示例

JBoss EAP 6 里包含了一个 H2 数据源,它是一个轻量级的关系型数据库管理系统,它为开发者提供了快速构建应用程序的能力,而且是平台的示例数据源。

警告

然而,JBoss EAP 附带的示例数据源不应该用于产品环境。它是一个非常小、自包容的数据源,它支持所有测试和构建应用程序所需的标准,但它并不健壮也不具有足够的可扩充性以用于产品环境。
关于被支持和认证的数据源,请参考 第 6.1.2 节 “JBoss EAP 6 支持的数据库”

6.1.5. -ds.xml 文件的部署

在 JBoss EAP 6 里,数据源被定义为服务器子系统的资源。在以前的版本里,服务器配置的 deploy 目录里要求有 *-ds.xml 数据源配置文件。*-ds.xml 文件仍可以按照Schemas 这里http://www.ironjacamar.org/documentation.html 的 1.1 数据源模式部署在 JBoss EAP 6 里。

警告

这个功能应该只用于部署。我们不推荐将其用于产品环境,因为 JBoss 管理工具并不支持它。

重要

当部署 *-ds.xml 文件时,使用对已部署 / 定义的<driver> 条目的引用是强制的。

6.2. JDBC 驱动

6.2.1. 用管理控制台安装 JDBC 驱动

介绍

在你的应用程序可以连接 JDBC 数据源之前,你的数据源供应商的 JDBC 驱动需要安装在 JBoss EAP 可以使用的位置上。JBoss EAP 6 允许你象其他部署一样部署这些驱动。这意味着如果你使用了受管域,你可以将它们部署在服务器组里的多个服务器上。

注意

考虑到更好的服务器启动行为,JDBC 驱动的首选安装方法是作为核心模块安装。要将 JDBC 驱动安装为核心模块,请参考:第 6.2.2 节 “将 JDBC 驱动安装为核心模块”
先决条件

在执行这个任务之前,你需要满足以下预备条件:

  • 从数据库供应商下载 JDBC 驱动。

过程 6.1. 部署 JDBC 驱动

  1. 访问管理控制台。

  2. 将 JAR 文件部署到服务器或服务器组。

    如果你使用了受管域,你可以将 JAR 文件部署到服务器组。否则,部署到自己的服务器。请参考 第 9.2.2 节 “使用管理控制台部署应用程序”
结果:

JDBC 驱动被部署,可由你的应用程序所使用。

6.2.2. 将 JDBC 驱动安装为核心模块

先决条件

在执行这个任务之前,你需要满足以下预备条件:

过程 6.2. 将 JDBC 驱动安装为核心模块

  1. EAP_HOME/modules/ 目录下创建一个文件路径结构。例如,对于 MySQL JDBC 驱动,创建下列目录结构:EAP_HOME/modules/com/mysql/main/
  2. 将 JDBC 驱动的 JAR 文件复制到 main/ 子目录。
  3. main/ 子目录里,创建一个类似于下列示例的 module.xml 文件: 第 7.1.1 节 “模块”module XSD 在 EAP_HOME/docs/schema/module-1_2.xsd 文件里进行定义。
  4. 启动服务器。
  5. 启动管理 CLI。
  6. 运行下列 CLI 命令将 JDBC 模块添加为驱动:
    /subsystem=datasources/jdbc-driver=DRIVER_NAME:add(driver-name=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xa-datasource-class-name=XA_DATASOURCE_CLASS_NAME)

    例 6.1. CLI 名利示例

    /subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource)
结果

已安装好 JDBC 驱动并设置为核心模块,且可以被应用程序数据源引用。

6.2.3. JDBC 驱动的下载位置

下表列出了 JBoss EAP 6 常用的数据库的 JDBC 驱动的下载位置。这些链接指向不受 Red Hat 监控或控制的第三方网站。关于您的数据库的最新驱动,请参考相关数据库供应商的文档和网站。

6.2.4. 访问供应商专有的类

总结

本节涵盖使用 JDBC 专有类所需的步骤。当应用程序需要使用非 JDBC API 一部分的供应商专有功能时这是有必要的。

警告

这是高级的应用。只有需要 JDBC API 里找不到的功能时才应该实现这个过程。

重要

在使用重验证机制并访问供应商专有的类时这个过程是必需的。

重要

因为这个连接是被 Iron Jacamar 容器控制的,请严格遵循供应商专有的 API 准则。

过程 6.3. 在应用程序里添加依赖关系

    • 配置 MANIFEST.MF 文件

      1. 在文本编辑器里打开应用程序的 META-INF/MANIFEST.MF 文件。
      2. 为 JDBC 模块添加一个依赖关系并保存文件。
        依赖关系:MODULE_NAME

        例 6.2. 依赖关系示例

        依赖关系:com.mysql
      1. 创建一个 jboss-deployment-structure.xml 文件

        在应用程序的 META-INF/ or WEB-INF 文件夹里创建一个名为 jboss-deployment-structure.xml 的文件。

        例 6.3. jboss-deployment-structure.xml 文件示例

        <jboss-deployment-structure>
          <deployment>
            <dependencies>
              <module name="com.mysql" />
            </dependencies>
          </deployment>
        </jboss-deployment-structure>
        
        

例 6.4. 访问供应商专有的 API

下面的例子访问了 MySQL API。
import java.sql.Connection;
import org.jboss.jca.adapters.jdbc.WrappedConnection;

  Connection c = ds.getConnection();
  WrappedConnection wc = (WrappedConnection)c;
  com.mysql.jdbc.Connection mc = wc.getUnderlyingConnection();

6.3. Non-XA 数据源

6.3.1. 用管理界面创建一个 Non-XA 数据源

总结

本节涵盖用管理控制台或管理 CLI 创建 Non-XA 数据源所需的步骤。

前提条件

  • JBoss EAP 6 服务器必须正在运行。

注意

在 Oracle 数据源 10.2 之前的版本里,<no-tx-separate-pools/> 参数是必需的,因为非事务性和事务性连接的混合可能导致错误。对于某些应用程序来说,这个参数已不再是必需的了。

过程 6.4. 用管理 CLI 或管理控制台创建一个数据源

    • 管理 CLI

      1. 启动 CLI 工具并连接到您的服务器。
      2. 运行下列命令来创建 Non-XA 数据源,配置合适的变量:
        data-source add --name=DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME  --connection-url=CONNECTION_URL
      3. 启用数据源:
        data-source enable --name=DATASOURCE_NAME
    • 管理控制台

      1. 登陆到管理控制台。
      2. 进入管理控制台的 Datasources 面板

          • 独立模式

            从控制台的顶部选择 Profile 标签页。
          • 域模式

            1. 从控制台的顶部选择 Profiles 标签页。
            2. 从左上角的下拉菜单里选择合适的配置集。
            3. 展开控制台左侧的 Subsystems 菜单。
        1. 从控制台左侧的菜单里选择 ConnectorDatasources
      3. 创建新的数据源

        1. 选择 Datasources 面板顶部的 Add 按钮。
        2. Create Datasource 向导里输入新的数据源属性并点击 Next 按钮。
        3. Create Datasource 向导里输入 JDBC 驱动细节并点击 Next 按钮。
        4. Create Datasource 向导里输入连接设置并点击 Done 按钮。
结果

Non-XA 数据源已被添加至服务器。它在 standalone.xmldomain.xml 文件以及管理界面里都可见。

6.3.2. 用管理界面修改 Non-XA 数据源

总结

本节涵盖用管理控制台或管理 CLI 修改 Non-XA 数据源所需的步骤。

注意

Non-XA 数据源可以和 JTA 事务继承。要继承数据源和 JTA,请确保 jta 参数被设置为 true

过程 6.5. 修改 Non-XA 数据源

    • 管理 CLI

      1. 使用 write-attribute 命令来配置数据源属性:
        /subsystem=datasources/data-source=DATASOURCE_NAME:write-attribute(name=ATTRIBUTE_NAME,value=ATTRIBUTE_VALUE)
      2. 重载服务器来确认修改:
        :reload
    • 管理控制台

      1. 进入管理控制台的 Datasources 面板

          • 独立模式

            从控制台的顶部选择 Profile 标签页。
          • 域模式

            1. 从控制台的顶部选择 Profiles 标签页。
            2. 从左上角的下拉菜单里选择合适的配置集。
            3. 展开控制台左侧的 Subsystems 菜单。
        1. 从控制台左侧的菜单里选择 ConnectorDatasources
      2. 编辑数据源

        1. Available Datasources 列表里选择相关的数据源。数据源属性显示在下面的 Attributes 面板上。
        2. 选择 Edit 按钮来编辑数据源属性。
        3. 编辑数据源属性并在完成时选择 Save 按钮。
结果

已完成对 Non-XA 数据源的配置。这些修改在 standalone.xmldomain.xml 文件以及管理界面里都可见。

6.3.3. 用管理界面删除 Non-XA 数据源

总结

本节涵盖用管理控制台或管理 CLI 从 JBoss EAP 6 删除 Non-XA 数据源所需的步骤。

过程 6.6. 删除 Non-XA 数据源

    • 管理 CLI

      1. 运行下列命令来删除 Non-XA 数据源:
        data-source remove --name=DATASOURCE_NAME
    • 管理控制台

      1. 进入管理控制台的 Datasources 面板

          • 独立模式

            从控制台的顶部选择 Profile 标签页。
          • 域模式

            1. 从控制台的顶部选择 Profiles 标签页。
            2. 从左上角的下拉菜单里选择合适的配置集。
            3. 展开控制台左侧的 Subsystems 菜单。
        1. 从控制台左侧的菜单里选择 ConnectorDatasources
      2. 选择要删除的数据源,并点击控制台右上角的 Remove 按钮。
结果

非 XA 数据源已从服务器删除。

6.4. XA 数据源

6.4.1. 用管理界面创建 XA 数据源

总结

本节涵盖用管理控制台或管理 CLI 创建 XA 数据源所需的步骤。

注意

在 Oracle 数据源 10.2 之前的版本里,<no-tx-separate-pools/> 参数是必需的,因为非事务性和事务性连接的混合可能导致错误。对于某些应用程序来说,这个参数已不再是必需的了。

过程 6.7. 用管理 CLI 或管理控制台创建 XA 数据源

    • 管理 CLI

      1. 运行下列命令来创建 XA 数据源,配置合适的变量:
        xa-data-source add --name=XA_DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME --xa-datasource-class=XA_DATASOURCE_CLASS
      2. 配置 XA 数据源属性

        1. 设置服务器名称

          运行下列命令来配置主机的服务器名称:
          /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=ServerName:add(value=HOSTNAME)
        2. 设置数据库名称

          运行下列命令来配置数据库名称:
          /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=DatabaseName:add(value=DATABASE_NAME)
      3. 启用数据源:
        xa-data-source enable --name=XA_DATASOURCE_NAME
    • 管理控制台

      1. 进入管理控制台的 Datasources 面板

          • 独立模式

            从控制台的顶部选择 Profile 标签页。
          • 域模式

            1. 从控制台的顶部选择 Profiles 标签页。
            2. 从左上角的下拉菜单里选择合适的配置集。
            3. 展开控制台左侧的 Subsystems 菜单。
        1. 从控制台左侧的菜单里选择 ConnectorDatasources
      2. 选择 XA Datasource 标签页。
      3. 创建新的 XA 数据源

        1. 选择 XA Datasources 面板顶部的 Add 按钮。
        2. Create XA Datasource 向导里输入新的 XA 数据源属性并点击 Next 按钮。
        3. Create XA Datasource 向导里输入 JDBC 驱动细节并点击 Next 按钮。
        4. 编辑 XA 属性并点击 Next 按钮。
        5. Create XA Datasource 向导里输入连接设置并点击 Done 按钮。
结果

XA 数据源已被添加至服务器。它在 standalone.xmldomain.xml 文件以及管理界面里都可见。

6.4.2. 用管理界面修改 XA 数据源

总结

本节涵盖用管理控制台或管理 CLI 修改 XA 数据源所需的步骤。

过程 6.8. 用管理 CLI 或管理控制台修改 XA 数据源

    • 管理 CLI

      1. 配置 XA 数据源属性

        使用 write-attribute 命令来配置数据源属性:
        /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME:write-attribute(name=ATTRIBUTE_NAME,value=ATTRIBUTE_VALUE)
      2. 配置 XA 数据源属性

        运行下列命令来配置 XA 数据源子资源:
        /subsystem=datasources/xa-data-source=DATASOURCE_NAME/xa-datasource-properties=PROPERTY_NAME:add(value=PROPERTY_VALUE)
      3. 重载服务器来确认修改:
        :reload
    • 管理控制台

      1. 进入管理控制台的 Datasources 面板

          • 独立模式

            从控制台的顶部选择 Profile 标签页。
          • 域模式

            1. 从控制台的顶部选择 Profiles 标签页。
            2. 从左上角的下拉菜单里选择合适的配置集。
            3. 展开控制台左侧的 Subsystems 菜单。
        1. 从控制台左侧的菜单里选择 ConnectorDatasources
      2. 选择 XA Datasource 标签页。
      3. 编辑数据源

        1. Available XA Datasources 列表里选择相关的数据源。XA 数据源属性显示在下面的 Attributes 面板上。
        2. 选择 Edit 按钮来编辑数据源属性。
        3. 编辑 XA 数据源属性并在完成时选择 Save 按钮。
结果

已完成对 XA 数据源的配置。这些修改在 standalone.xmldomain.xml 文件以及管理界面里都可见。

6.4.3. 用管理界面删除 XA 数据源

总结

本节涵盖用管理控制台或管理 CLI 从 JBoss EAP 6 删除 XA 数据源所需的步骤。

过程 6.9. 用管理 CLI 或管理控制台删除 XA 数据源

    • 管理 CLI

      1. 运行下列命令来删除 XA 数据源:
        xa-data-source remove --name=XA_DATASOURCE_NAME
    • 管理控制台

      1. 进入管理控制台的 Datasources 面板

          • 独立模式

            从控制台的顶部选择 Profile 标签页。
          • 域模式

            1. 从控制台的顶部选择 Profiles 标签页。
            2. 从左上角的下拉菜单里选择合适的配置集。
            3. 展开控制台左侧的 Subsystems 菜单。
        1. 从控制台左侧的菜单里选择 ConnectorDatasources
      2. 选择 XA Datasource 标签页。
      3. 选择要删除的 XA 数据源,并点击控制台右上角的 Remove 按钮。
结果

XA 数据源已从服务器删除。

6.4.4. XA 恢复

6.4.4.1. 关于 XA Recovery 模块
每个 XA 资源都需要一个 recovery 模块与其配置相关联。这个 recovery 模块必须继承 com.arjuna.ats.jta.recovery.XAResourceRecovery
JBoss EAP 6 为 JDBC 和 JMS XA 资源提供了 recovery 模块。对于这些类型的资源,recovery 模块会自动注册。如果您需要使用自定义模块,您可以在自己的数据源里注册它。
6.4.4.2. 配置 XA Recovery 模块
对于多数 JDBC 和 JMS 资源,recovery 模块自动和资源相关联。在这些情况下,您只需要配置选项以允许 recovery 模块连接到您的资源来执行恢复。
对于非 JDBC 或 JMS 的自定义资源,请联系 Red Hat 全球支持服务获取受支持的配置的信息。
每个配置属性都可以在数据源创建过程中或之后设置。你可以用基于 web 的管理控制台或命令行管理 CLI 进行设置。关于配置 XA 数据源的信息,请参考 第 6.4.1 节 “用管理界面创建 XA 数据源”第 6.4.2 节 “用管理界面修改 XA 数据源”
参考下列表里的常用数据源配置属性,以及和专有数据库供应商相关的配置细节。
Expand
表 6.2. 常用的配置属性
属性 描述
recovery-username
recovery 模块应该用来连接资源进行恢复的用户名。
recovery-password
recovery 模块应该用来连接资源进行恢复的密码。
recovery-security-domain
recovery 模块应该用来连接资源进行恢复的安全域。
recovery-plugin-class-name
如果你需要使用自定义的 recovery 模块,请将这个属性设置为模块的全限定名。这个模块应该继承 com.arjuna.ats.jta.recovery.XAResourceRecovery 类。
recovery-plugin-properties
如果你使用了要求设置属性的自定义 recovery 模块,请将这个属性设置为用逗号隔开的 key=value 对的列表。

供应商专有的配置信息

Oracle
如果错误地配置了 Oracle 数据源,您可能会在日志输出里看到这样的错误:
WARN  [com.arjuna.ats.jta.logging.loggerI18N] [com.arjuna.ats.internal.jta.recovery.xarecovery1] Local XARecoveryModule.xaRecovery  got XA exception javax.transaction.xa.XAException, XAException.XAER_RMERR
要解决这个错误,请确保 recovery-username 里配置的 Oracle 用户可以访问恢复所需的表。下面是安装了 Oracle bug 5945463 补丁的 Oracle 11g 或 Oracle 10g R2 实例的正确 Grant SQL 语句。
GRANT SELECT ON sys.dba_pending_transactions TO recovery-username;
GRANT SELECT ON sys.pending_trans$ TO recovery-username;
GRANT SELECT ON sys.dba_2pc_pending TO recovery-username;
GRANT EXECUTE ON sys.dbms_xa TO recovery-username;
如果你使用了 11g 以前的 Oracle 11 版本,请将最后的 EXECUTE 语句修改为:
	GRANT EXECUTE ON sys.dbms_system TO recovery-username;
PostgreSQL
关于启用 pepared (也就是 XA)事务的说明请阅读 PostgreSQL 文档。PostgreSQL 的 JDBC 驱动的 8.4-701 版本在 org.postgresql.xa.PGXAConnection 里有一个程序错误,它在某些情况下会中断恢复。在更新的版本里我们会修复这个问题。
MySQL
根据 http://bugs.mysql.com/bug.php?id=12161,XA 事务恢复在 MySQL 5 的某些版本里无法运行。MySQL 6.1 里已解决了这个问题。详情请参考 bug URL 或 MySQL 文档。
IBM DB2
IBM DB2 期望 XAResource.recover 方法只是在应用服务器发生崩溃或故障后重启时的重同步阶段才被调用。这是 DB2 实现里的设计问题,超出了本文档的范畴。

6.5. 数据源安全性

6.5.1. 关于数据源安全性

数据源安全性的首选方案是使用安全域或密码阀。下面是它们各自的例子。关于更多的信息,请参考:

例 6.5. 安全域示例

<security>
   <security-domain>mySecurityDomain</security-domain>
</security>

例 6.6. 密码阀示例

<security>
  <user-name>admin</user-name>
  <password>${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}</password>
</security>

6.6. 数据源配置

6.6.1. 数据源参数

Expand
表 6.3. XA 和非 XA 数据源共用的数据源参数
参数 描述
jndi-name 数据源的唯一 JNDI 名称。
pool-name 数据源的管理池的名称。
enabled 是否启用数据源
use-java-context
是否绑定数据源到全局 JNDI。
spy
启用 JDBC 层的 spy 功能。这会将所有 JDBC 通讯记录到数据源。logging-category 参数也必须设置为 org.jboss.jdbc
use-ccm 启用缓存连接管理者。
new-connection-sql 当连接被添加到连接池时会执行的 SQL 语句。
transaction-isolation
下列值之一:
  • TRANSACTION_READ_UNCOMMITTED
  • TRANSACTION_READ_COMMITTED
  • TRANSACTION_REPEATABLE_READ
  • TRANSACTION_SERIALIZABLE
  • TRANSACTION_NONE
url-delimiter 用于高可用性(HA)群集数据库的 connection-url 的分隔符。
url-selector-strategy-class-name 实现 org.jboss.jca.adapters.jdbc.URLSelectorStrategy 接口的类。
security
包含设置安全性的子元素。请参考 表 6.8 “安全性参数”
validation
包含设置有效性的子元素。 请参考 表 6.9 “用于检验的参数”
timeout
包含设置超时的子元素。请参考 表 6.10 “超时参数”
statement
包含设置语句的子元素。请参考 表 6.11 “语句参数”
Expand
表 6.4. Non-XA 数据源参数
参数 描述
jta 为非 XA 数据源启动 JTA 集成。不适用于 XA 数据源。
connection-url JDBC 驱动连接的 URL。
driver-class JDBC 驱动类的全限定名。
connection-property
传递给 Driver.connect(url,props) 方法的任意连接属性。每个 connection-property 都指定一个字符串/值对。属性名称来自元素名称,而值来自元素的内容。
pool
包含设置池的子元素。请参考 表 6.6 “non-XA 和 XA 数据源公用的池参数”
Expand
表 6.5. XA 数据源参数
参数 描述
xa-datasource-property
分配给 XADataSource 类实现的属性。通过 name=value 指定。如果存在 setName 格式的 setter 方法,这个属性将通过调用 setName(value) 格式的 setter 方法来设置。
xa-datasource-class
javax.sql.XADataSource 实现的全限定名。
driver
对包含 JDBC 驱动的 classloader 模块的唯一引用。有效的格式是 driverName#majorVersion.minorVersion
xa-pool
recovery
包含设置恢复的子元素。请参考 表 6.12 “恢复参数”
Expand
表 6.6. non-XA 和 XA 数据源公用的池参数
参数 描述
min-pool-size 池里可保留的连接的最小数量。
max-pool-size 池里可保留的连接的最大数量。
prefill 是否预先填充连接池。空的元素表示 true 值。默认为 false
use-strict-min pool-size 是否是严格规定的。默认为 false
flush-strategy
在发生错误时是否冲刷池。有效值为:
  • FailingConnectionOnly
  • IdleConnections
  • EntirePool
默认值为 FailingConnectionOnly
allow-multiple-users 指定是否有多个用户将通过 getConnection(user, password) 访问数据源,且内部池类型是否应该计入在内。
Expand
表 6.7. XA 池参数
参数 描述
is-same-rm-override javax.transaction.xa.XAResource.isSameRM(XAResource) 类是否返回 truefalse
interleaving 是否启用 XA 连接工厂的 interleaving。
no-tx-separate-pools 是否为每个上下文创建单独的子池。对于 Oracel 数据源来说这是必需的,它不允许 XA 连接既在 JTA 内部又在外部使用。
pad-xid 是否拆分 Xid。
wrap-xa-resource
是否将 XAResource 包裹在 org.jboss.tm.XAResourceWrapper 实例里。
Expand
表 6.8. 安全性参数
参数 描述
user-name 创建新连接使用的用户名。
password 创建新连接使用的密码。
security-domain 非 XA 数据源参数
reauth-plugin 定义一个重验证插件以用于重新验证物理连接。
Expand
表 6.9. 用于检验的参数
参数 描述
valid-connection-checker
提供 SQLException.isValidConnection(Connection e) 方法来检验连接的 org.jboss.jca.adaptors.jdbc.ValidConnectionChecker 接口的实现。异常表示连接已被销毁。它覆盖了 check-valid-connection-sql 参数(如果存在)。
check-valid-connection-sql 检查池连接有效性的 SQL 语句。当从池里获取受管连接进行使用时它会被调用。
validate-on-match
指定当连接工厂试图对给定的集合匹配受管连接时是否执行连接级别的检验。
我们通常不会同时指定 validate-on-matchbackground-validation 为 true。但客户在使用连接前必须进行检验时则需要 Validate-on-match。这个参数默认为 true。
background-validation
指定连接在背景线程上进行检验。背景检验不和 validate-on-match 一起使用是一种性能优化。如果 validate-on-match 为 true 时,使用 background-validation 可能导致冗余的检查。背景检验可能会让用户用到有问题的连接(连接在返回给客户和检验扫描之间可能会出现问题),所以客户应用程序必须考虑到这种可能性。
background-validation-millis 背景检验运行的时间(毫秒)。
use-fast-fail
如果为 true,在第一次尝试时如果连接无效则失败。默认为 false
stale-connection-checker
提供 Boolean isStaleConnection(SQLException e) 方法的 org.jboss.jca.adapters.jdbc.StaleConnectionChecker 实例。如果这个方法返回 true,异常将包裹在 org.jboss.jca.adapters.jdbc.StaleConnectionExceptionSQLException 的子类)里。
exception-sorter
提供 Boolean isExceptionFatal(SQLException e) 方法的 org.jboss.jca.adapters.jdbc.ExceptionSorter 实例。这个方法检验异常是否作为 connectionErrorOccurred 消息传播到所有的 javax.resource.spi.ConnectionEventListener 实例上。
Expand
表 6.10. 超时参数
参数 描述
use-try-lock 使用 tryLock() 而不是 lock()。在指定秒数内试图获取锁,而不是在锁不可用时立即失败。默认值为 60 秒。如果超时为 5 分钟,则应设置 <use-try-lock>300</use-try-lock>
blocking-timeout-millis 等待连接时阻塞的最长时间(毫秒)。超过这个时间后,异常将被抛出。这只是在等待连接许可时阻塞,如果创建新连接花费很长时间并不会抛出异常。默认值为 30000,也就是 30 秒。
idle-timeout-minutes
在空闲连接关闭前的最长等待时间(分钟)。实际的最长时间取决于 idleRemover 扫描时间,它是任何池的最小 idle-timeout-minutes 的一半。
set-tx-query-timeout
是否根据事务超时前剩下的时间设置查询超时。如果没有事务存在则使用任何配置好的查询超时时间。默认为 false
query-timeout 查询的超时时间(秒)。默认是无超时。
allocation-retry 在抛出异常前,重新尝试分配连接的次数。默认为 0,异常将在第一次失败时抛出。
allocation-retry-wait-millis
在重新分配连接前应等待的时间(毫秒)。默认值是 5000,也就是 5 秒。
xa-resource-timeout
如果为非零值,这个值将传递给 XAResource.setTransactionTimeout 方法。
Expand
表 6.11. 语句参数
参数 描述
track-statements
当连接返回池且语句返回到 prepared 语句缓存时是否检测未关闭的语句。如果为 false,则不会对语句进行追踪。
  • true: : 对语句和结果集进行跟踪,如果没有关闭则提示警告。
  • false: 对语句和结果集都不进行跟踪。
  • nowarn: 语句将被跟踪但不会发出警告。这是默认设置。
prepared-statement-cache-size 每个连接的 prepared 语句的个数,存在于 Least Recently Used (LRU) 缓存里。
share-prepared-statements
是否两次请求相同的底层 prepared 语句而不关闭它。默认是 false
Expand
表 6.12. 恢复参数
参数 描述
recover-credential 安全域用于恢复的用户名/密码对。
recover-plugin
用于恢复的 org.jboss.jca.core.spi.recoveryRecoveryPlugin 类。

6.6.2. 数据源连接 URL

Expand
表 6.13. 
数据源 数据源 URL
PostgreSQL jdbc:postgresql://SERVER_NAME:PORT/DATABASE_NAME
MySQL jdbc:mysql://SERVER_NAME:PORT/DATABASE_NAME
Oracle jdbc:oracle:thin:@ORACLE_HOST:PORT:ORACLE_SID
IBM DB2 jdbc:db2://SERVER_NAME:PORT/DATABASE_NAME
Microsoft SQLServer jdbc:microsoft:sqlserver://SERVER_NAME:PORT;DatabaseName=DATABASE_NAME

6.6.3. 数据源扩展

数据源部署可以使用 JDBC 资源适配器里的几个扩展来改进连接检验,并检查异常是否应该重新建立连接。这些扩展是:
Expand
表 6.14. 数据源扩展
数据源扩展 配置参数 描述
org.jboss.jca.adapters.jdbc.spi.ExceptionSorter <exception-sorter> 检查 SQLException 对于抛出它的连接是否是毁灭性的
org.jboss.jca.adapters.jdbc.spi.StaleConnection <stale-connection-checker> 将过时的 SQLExceptions 包裹在 org.jboss.jca.adapters.jdbc.StaleConnectionException
org.jboss.jca.adapters.jdbc.spi.ValidConnection <valid-connection-checker> 检查连接是否有效,能为应用程序所用。
JBoss EAP 6 也为几个受支持的数据库实现了这些扩展。

扩展实现

通用
  • org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.novendor.NullStaleConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker
PostgreSQL
  • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
MySQL
  • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
IBM DB2
  • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker
Sybase
  • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
Microsoft SQLServer
  • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker
Oracle
  • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker

6.6.4. 查看数据源统计

您可以用下列命令从定义的数据源里查看 jdbcpool 的统计信息:

过程 6.10. 

  • /subsystem=datasources/data-source=ExampleDS/statistics=jdbc:read-resource(include-runtime=true)
    
    /subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)
    

注意

确保您指定了 include-runtime=true 参数,因为所有统计都是 runtime 信息。默认值为 false

6.6.5. 数据源统计

核心统计信息

下表包含受支持的数据源核心统计信息列表:

Expand
表 6.15. 核心统计信息
名称 描述
ActiveCount
活动连接的数量。每个连接都是正在被应用程序使用或是在池里备用。
AvailableCount
池里可用连接的数量。
AverageBlockingTime
获取池里排他锁时阻塞的平均时间。单位为毫秒。
AverageCreationTime
创建连接所花费的平均时间。单位为毫秒。
CreatedCount
创建的连接数量。
DestroyedCount
销毁的连接数量。
InUseCount
正在使用的连接的数量。
MaxCreationTime
创建连接所花费的最长时间。单位为毫秒。
MaxUsedCount
使用的连接的最大数目。
MaxWaitCount
同一时间等待连接的请求的最大数目。
MaxWaitTime
等待池里排他锁所花费的最长时间。
TimedOut
超时连接的数量。
TotalBlockingTime
等待池里排他锁总共所花费的时间。单位为毫秒。
TotalCreationTime
创建连接总共所花费的时间。单位为毫秒。
WaitCount
需要等待连接的请求的数量。
JDBC 统计信息

下表包含受支持的数据源 JDBC 统计信息列表:

Expand
表 6.16. JDBC 统计信息
名称 描述
PreparedStatementCacheAccessCount
语句缓存被访问的次数。
PreparedStatementCacheAddCount
添加到语句缓存里的语句数量。
PreparedStatementCacheCurrentSize
目前缓存在语句缓存里的 prepared 和可调用的语句的数量。
PreparedStatementCacheDeleteCount
从缓存里丢弃的语句的数量。
PreparedStatementCacheHitCount
语句在缓存里被使用的次数。
PreparedStatementCacheMissCount
对缓存里语句的请求无法被满足的次数。

6.7. 示例数据源

6.7.1. PostgreSQL 数据源示例

例 6.7. 

下面的例子是一个 PostgreSQL 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <datasource jndi-name="java:jboss/PostgresDS" pool-name="PostgresDS">
    <connection-url>jdbc:postgresql://localhost:5432/postgresdb</connection-url>
    <driver>postgresql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"></valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"></exception-sorter>
    </validation>
  </datasource>
  <drivers>
    <driver name="postgresql" module="org.postgresql">
      <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>

下面是用于上面的 PostgreSQL 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="org.postgresql">
  <resources>
    <resource-root path="postgresql-9.1-902.jdbc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.2. PostgreSQL XA 数据源示例

例 6.8. 

下面的例子是一个 PostgreSQL XA 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <xa-datasource jndi-name="java:jboss/PostgresXADS" pool-name="PostgresXADS">
    <driver>postgresql</driver>
    <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
    <xa-datasource-property name="PortNumber">5432</xa-datasource-property>
    <xa-datasource-property name="DatabaseName">postgresdb</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker">
      </valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter">
      </exception-sorter>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="postgresql" module="org.postgresql">
      <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>

下面是用于上面的 PostgreSQL XA 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="org.postgresql">
  <resources>
    <resource-root path="postgresql-9.1-902.jdbc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.3. MySQL 数据源示例

例 6.9. 

下面的例子是一个 MySQL 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <datasource jndi-name="java:jboss/MySqlDS" pool-name="MySqlDS">
    <connection-url>jdbc:mysql://mysql-localhost:3306/jbossdb</connection-url>
    <driver>mysql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security> 
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"></valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"></exception-sorter>
    </validation>
  </datasource>
  <drivers>
    <driver name="mysql" module="com.mysql">
      <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>

下面是用于上面的 MySQL 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-5.0.8-bin.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.4. MySQL XA 数据源示例

例 6.10. 

下面的例子是一个 MySQL XA 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <xa-datasource jndi-name="java:jboss/MysqlXADS" pool-name="MysqlXADS">
  <driver>mysql</driver>
    <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
    <xa-datasource-property name="DatabaseName">mysqldb</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"></valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"></exception-sorter>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="mysql" module="com.mysql">
      <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>

下面是用于上面的 MySQL XA 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-5.0.8-bin.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.5. Oracle 数据源示例

注意

在 Oracle 数据源 10.2 之前的版本里,<no-tx-separate-pools/> 参数是必需的,因为非事务性和事务性连接的混合可能导致错误。对于某些应用程序来说,这个参数已不再是必需的了。

例 6.11. 

下面的例子是一个 Oracle 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <datasource jndi-name="java:/OracleDS" pool-name="OracleDS">
    <connection-url>jdbc:oracle:thin:@localhost:1521:XE</connection-url>
    <driver>oracle</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security> 
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"></valid-connection-checker>
      <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker"></stale-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"></exception-sorter>
    </validation>
  </datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
      <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>

下面是用于上面的 Oracle 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="com.oracle">
  <resources>
    <resource-root path="ojdbc6.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.6. Oracle XA 数据源示例

注意

在 Oracle 数据源 10.2 之前的版本里,<no-tx-separate-pools/> 参数是必需的,因为非事务性和事务性连接的混合可能导致错误。对于某些应用程序来说,这个参数已不再是必需的了。

重要

下面的设置必须应用于访问 Oracle XA 数据源的用户以使 XA 恢复可以正常操作。user 的值是连接 JBoss 到 Oracle 的用户:
  • GRANT SELECT ON sys.dba_pending_transactions TO user;
  • GRANT SELECT ON sys.pending_trans$ TO user;
  • GRANT SELECT ON sys.dba_2pc_pending TO user;
  • GRANT EXECUTE ON sys.dbms_xa TO user; (If using Oracle 10g R2 (patched) or Oracle 11g)
    OR
    GRANT EXECUTE ON sys.dbms_system TO user; (If using an unpatched Oracle version prior to 11g)

例 6.12. 

下面的例子是一个 Oracle XA 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <xa-datasource jndi-name="java:/XAOracleDS" pool-name="XAOracleDS">
    <driver>oracle</driver>
    <xa-datasource-property name="URL">jdbc:oracle:oci8:@tc</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
      <no-tx-separate-pools />
    </xa-pool>
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"></valid-connection-checker>
      <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker"></stale-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"></exception-sorter>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
      <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>

下面是用于上面的 Oracle XA 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="com.oracle">
  <resources>
    <resource-root path="ojdbc6.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.7. Microsoft SQLServer 数据源示例

例 6.13. 

下面的例子是一个 Microsoft SQLServer 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <datasource jndi-name="java:/MSSQLDS" pool-name="MSSQLDS">
    <connection-url>jdbc:microsoft:sqlserver://localhost:1433;DatabaseName=MyDatabase</connection-url>
    <driver>sqlserver</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"></valid-connection-checker>
    </validation>
  </datasource>
  <drivers>
    <driver name="sqlserver" module="com.microsoft">
      <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class>
    </driver>
</datasources>

下面是用于上面的 Microsoft SQLServer 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="com.microsoft">
  <resources>
    <resource-root path="sqljdbc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.8. Microsoft SQLServer XA 数据源示例

例 6.14. 

下面的例子是一个 Microsoft SQLServer XA 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <xa-datasource jndi-name="java:/MSSQLXADS" pool-name="MSSQLXADS">
    <driver>sqlserver</driver>
    <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
    <xa-datasource-property name="DatabaseName">mssqldb</xa-datasource-property>
    <xa-datasource-property name="SelectMethod">cursor</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"></valid-connection-checker>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="sqlserver" module="com.microsoft">
      <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>

下面是用于上面的 Microsoft SQLServer XA 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="com.microsoft">
  <resources>
    <resource-root path="sqljdbc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.9. IBM DB2 数据源示例

例 6.15. 

下面的例子是一个 IBM DB2 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <datasource jndi-name="java:/DB2DS" pool-name="DB2DS">
    <connection-url>jdbc:db2:ibmdb2db</connection-url>
    <driver>ibmdb2</driver>
    <pool>
      <min-pool-size>0</min-pool-size>
      <max-pool-size>50</max-pool-size>
    </pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security> 
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"></valid-connection-checker>
      <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker"></stale-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"></exception-sorter>
    </validation>
  </datasource>
  <drivers>
    <driver name="ibmdb2" module="com.ibm">
      <xa-datasource-class>com.ibm.db2.jdbc.DB2XADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>

下面是用于上面的 IBM DB2 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="com.ibm">
  <resources>
    <resource-root path="db2jcc.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.10. IBM DB2 XA 数据源示例

例 6.16. 

下面的例子是一个 IBM DB2 XA 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <xa-datasource jndi-name="java:/DB2XADS" pool-name="DB2XADS">
    <driver>ibmdb2</driver>
    <xa-datasource-property name="DatabaseName">ibmdb2db</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"></valid-connection-checker>
      <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker"></stale-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"></exception-sorter>
    </validation>
    <recovery>
      <recover-plugin class-name="org.jboss.jca.core.recovery.ConfigurableRecoveryPlugin">
        <config-property name="EnableIsValid">false</config-property>
        <config-property name="IsValidOverride">false</config-property>
        <config-property name="EnableClose">false</config-property>
      </recover-plugin>
    </recovery>
  </xa-datasource>
  <drivers>
    <driver name="ibmdb2" module="com.ibm">
      <xa-datasource-class>com.ibm.db2.jcc.DB2XADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>

下面是用于上面的 IBM DB2 XA 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="com.ibm">
  <resources>
    <resource-root path="db2jcc.jar"/>
    <resource-root path="db2jcc_license_cisuz.jar"/>
    <resource-root path="db2jcc_license_cu.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.11. Sybase 数据源示例

例 6.17. 

下面的例子是一个 Sybase 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <datasource jndi-name="java:jboss/SybaseDB" pool-name="SybaseDB" enabled="true">
    <connection-url>jdbc:sybase:Tds:localhost:5000/DATABASE?JCONNECT_VERSION=6</connection-url>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"></valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"></exception-sorter>
    </validation>
  </datasource>
  <drivers>
    <driver name="sybase" module="com.sybase">
      <datasource-class>com.sybase.jdbc2.jdbc.SybDataSource</datasource-class>
      <xa-datasource-class>com.sybase.jdbc3.jdbc.SybXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>

下面是用于上面的 Sybase 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="com.sybase">
  <resources>
    <resource-root path="jconn2.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.12. Sybase XA 数据源示例

例 6.18. 

下面的例子是一个 Sybase XA 数据源配置。这个数据源已被启用,用户已经添加并已设置了检验选项。
<datasources>
  <xa-datasource jndi-name="java:jboss/SybaseXADS" pool-name="SybaseXADS" enabled="true">
    <xa-datasource-property name="NetworkProtocol">Tds</xa-datasource-property>
    <xa-datasource-property name="ServerName">myserver</xa-datasource-property>
    <xa-datasource-property name="PortNumber">4100</xa-datasource-property>
    <xa-datasource-property name="DatabaseName">mydatabase</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <background-validation>true</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"></valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"></exception-sorter>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="sybase" module="com.sybase">
      <datasource-class>com.sybase.jdbc2.jdbc.SybDataSource</datasource-class>
      <xa-datasource-class>com.sybase.jdbc3.jdbc.SybXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>

下面是用于上面的 Sybase XA 数据源的 module.xml 文件示例。
<module xmlns="urn:jboss:module:1.1" name="com.sybase">
  <resources>
    <resource-root path="jconn2.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

第 7 章 配置模块

7.1. 简介

7.1.1. 模块

模块是用于类加载和依赖关系管理的类的逻辑组。JBoss EAP 6 使用两种模块类型,有时称为静态和动态模块。然而,这两者的区别只是它们打包的方式。所有模块都提供相同的功能。
静态模块
静态模块是在应用服务器的 EAP_HOME/modules/ 目录里进行预定义的。每个子目录都代表一个模块并包含一个或多个 JAR 文件和配置文件(module.xml)。模块的名称是在 module.xml 文件里定义的。所有应用服务器提供的 API 都是作为静态模块提供的,包括 Java EE API 以及其他 API(如 Jboss Logging)。

例 7.1. module.xml 文件示例

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-5.1.15.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

模块名 com.mysql 应该匹配这个模块的目录结构。
如果许多使用相同第三方库的应用程序部署在相同的服务器上,那么创建自定义静态模块就很有用。不是将这些库捆绑到每个应用程序,而是由 JBoss 管理员创建和安装包含这些库的模块。然后应用程序就可以声明对自定义静态模块的显性依赖关系。
动态模块
应用服务器为每个 JAR 或 WAR 部署(或 EAR 里的子部署)创建和加载动态模块。动态模块的名称源自部署的归档的名称。因为部署是作为模块加载的,它们可以配置依赖关系并被其他部署作为依赖关系使用。
模块只有在需要时才会加载。这通常只在具有显性或隐性依赖关系的应用程序部署时发生。

7.1.2. 全局模块

全局模块(Global Module)是 JBoss EAP 6 作为每个应用程序的依赖关系而提供的模块。将任何模块添加到应用服务器的全局模块列表里都可以使其成为全局模块,你并不需要修改模块。

7.1.3. 模块的依赖关系

模块依赖关系是某个模块要求另外一个模块的类行使功能的声明。模块可以声明对多个模块的依赖关系。当应用服务器加载一个模块时,模块类加载器将解析该模块的依赖关系并从每个依赖关系中添加类到 class path 里。如果无法找到指定的依赖关系,这个模块将加载失败。
部署的应用程序(JAR 和 WAR)将被加载为动态模块并使用依赖关系来访问 JBoss EAP 6 提供的 API。
依赖关系的类型有两种:explicit(显性的)和 implicit(隐性的)
显性依赖关系是由开发人员声明的。静态的模块可以在 modules.xml 文件里声明依赖关系。动态模块可以在 MANIFEST.MF 或 jboss-deployment-structure.xml 里声明依赖关系。
显性的依赖关系可以指定为可选项。加载可选依赖关系失败不会造成模块无法加载。然而,如果依赖关系之后变成可用的,它不会被添加到模块的 classpath 里。当加载模块时,依赖关系必须是可用的。
隐性的依赖关系在某些条件满足或在部署里发现元数据时自动由应用服务器添加。JBoss EAP 6 附带的 Java EE 6 API 是通过检测部署里的隐性依赖关系而添加的模块的示例。
我们可以配置部署排除特定的隐性依赖关系。这是通过 jboss-deployment-structure.xml 部署描述符文件来完成的。这常常发生在当应用程序捆绑某个版本的库文件,而应用服务器将试图将其添加为隐性依赖关系的时候。
模块的 Class path 包含自己的类及其直接的依赖关系。模块无法访问其中一个依赖关系的依赖关系类。然而,模块可以指定导出某个显性的依赖关系。导出的依赖关系将提供给任何依赖于导出它的模块的模块。

例 7.2. 模块依赖关系

模块 A 依赖于模块 B 而模块 B 依赖于模块 C。模块 A 可以访问模块 B 的类,模块 B 可以访问模块 C 的类。模块 A 无法访问模块 C 的类。
  • 模块 A 声明了对模块 C 的显性依赖关系,或者
  • 模块 B 导出它对模块 C 的依赖关系。

7.1.4. 子部署类加载器的隔离

EAR 里的每个子部署都是一个动态模块,它有自己的类加载器。在默认情况下,子部署可以访问其他子部署的资源。
如果子部署不应该访问其他子部署的资源(要求严格的子部署隔离),那么就可以启用隔离。
这个任务展示了服务器管理员在应用服务期上如何禁用子部署模块隔离。这会影响到所有的部署。

警告

这个任务要求您编辑服务器的 XML 配置文件。编辑前这个服务器必须先暂停,这是临时措施,最终版本的管理工具将会支持这种配置。
  1. 停止服务器

    暂停 JBoss EAP 服务器。
  2. 打开服务器配置文件

    在文本编辑器里打开服务器配置文件。
    对于受管域和独立服务器这个文件是不同的。此外也可能使用非默认的位置和文件名称。对于受管域和独立服务器,默认的配置文件分别是 domain/configuration/domain.xmlstandalone/configuration/standalone.xml
  3. 定位 EE 子系统配置

    在配置文件里找到 EE 子系统配置元素。配置文件的 <profile> 元素包含了几个子系统元素。EE 子系统元素的命名空间是 urn:jboss:domain:ee:1.0
    <profile>
    
       ...
    
       <subsystem xmlns="urn:jboss:domain:ee:1.0" />
    
       ...
    默认的配置有一个自闭合的标签,但自定义的配置可能有单独的开和合标签(里面可能还有其他元素),如:
    <subsystem xmlns="urn:jboss:domain:ee:1.0" ></subsystem>
  4. 如果需要则替换自闭合的标签

    如果 EE Subsystem 元素是一个单个的自闭合标签,那么请用合适的开和合标签来替换,如:
    <subsystem xmlns="urn:jboss:domain:ee:1.0" ></subsystem>
  5. 添加 ear-subdeployments-isolated 元素

    ear-subdeployments-isolated 元素添加为 EE Subsystem 元素的子元素并添加 false 内容,如:
    <subsystem xmlns="urn:jboss:domain:ee:1.0" ><ear-subdeployments-isolated>false</ear-subdeployments-isolated></subsystem>
  6. 期待服务器

    重新启动 JBoss EAP 服务器以使用新的配置运行。
结果:

服务器现在对于所有部署都禁用了 Subdeployment Module Isolation。

7.3. 添加模块到所有部署里

这个任务展示了 JBoss 管理员如何定义全局模块列表。

前提条件

  1. 您必须知道要配置为全局模块的模块的名称。关于 JBoss EAP 6 附带的静态模块的列表,请参考 第 7.4.1 节 “包括的模块”。如果这个模块是另外一个部署,请参考 第 7.4.2 节 “动态模块命名” 来确定模块名。

过程 7.1. 添加模块到全局模块列表里

  1. 进入 EE Subsystem 面板。
      • 独立模式

        从控制台的顶部选择 Profile 标签页。
      • 域模式

        1. 从控制台的顶部选择 Profiles 标签页。
        2. 从左上角的下拉菜单里选择合适的配置集。
        3. 展开控制台左侧的 Subsystems 菜单。
    1. 从控制台左侧的菜单里选择 ContainerEE
  2. 点击 Subsystem Defaults 部分的 Add 按钮。Create Module 对话框将会出现。
  3. 输入模块名以及模块 slot(可选)。
  4. 点击 Save 按钮来添加新的全局模块,或者点击 Cancel 链接中止。
    • 如果您点击了 Save 按钮,对话框将关闭而指定的模块将被添加到全局模块列表里。
    • 如果您点击了 Cancel,对话框将关闭且不会保存任何修改。
结果

添加到全局模块列表的模块将作为依赖关系添加到每个部署里。

7.4. 参考

7.4.1. 包括的模块

  • asm.asm
  • ch.qos.cal10n
  • com.google.guava
  • com.h2database.h2
  • com.sun.jsf-impl
  • com.sun.jsf-impl
  • com.sun.xml.bind
  • com.sun.xml.messaging.saaj
  • gnu.getopt
  • javaee.api
  • javax.activation.api
  • javax.annotation.api
  • javax.api
  • javax.ejb.api
  • javax.el.api
  • javax.enterprise.api
  • javax.enterprise.deploy.api
  • javax.faces.api
  • javax.faces.api
  • javax.inject.api
  • javax.interceptor.api
  • javax.jms.api
  • javax.jws.api
  • javax.mail.api
  • javax.management.j2ee.api
  • javax.persistence.api
  • javax.resource.api
  • javax.rmi.api
  • javax.security.auth.message.api
  • javax.security.jacc.api
  • javax.servlet.api
  • javax.servlet.jsp.api
  • javax.servlet.jstl.api
  • javax.transaction.api
  • javax.validation.api
  • javax.ws.rs.api
  • javax.wsdl4j.api
  • javax.xml.bind.api
  • javax.xml.jaxp-provider
  • javax.xml.registry.api
  • javax.xml.rpc.api
  • javax.xml.soap.api
  • javax.xml.stream.api
  • javax.xml.ws.api
  • jline
  • net.sourceforge.cssparser
  • net.sourceforge.htmlunit
  • net.sourceforge.nekohtml
  • nu.xom
  • org.antlr
  • org.apache.ant
  • org.apache.commons.beanutils
  • org.apache.commons.cli
  • org.apache.commons.codec
  • org.apache.commons.collections
  • org.apache.commons.io
  • org.apache.commons.lang
  • org.apache.commons.logging
  • org.apache.commons.pool
  • org.apache.cxf
  • org.apache.httpcomponents
  • org.apache.james.mime4j
  • org.apache.log4j
  • org.apache.neethi
  • org.apache.santuario.xmlsec
  • org.apache.velocity
  • org.apache.ws.scout
  • org.apache.ws.security
  • org.apache.ws.xmlschema
  • org.apache.xalan
  • org.apache.xerces
  • org.apache.xml-resolver
  • org.codehaus.jackson.jackson-core-asl
  • org.codehaus.jackson.jackson-jaxrs
  • org.codehaus.jackson.jackson-mapper-asl
  • org.codehaus.jackson.jackson-xc
  • org.codehaus.woodstox
  • org.dom4j
  • org.hibernate
  • org.hibernate.envers
  • org.hibernate.infinispan
  • org.hibernate.validator
  • org.hornetq
  • org.hornetq.ra
  • org.infinispan
  • org.infinispan.cachestore.jdbc
  • org.infinispan.cachestore.remote
  • org.infinispan.client.hotrod
  • org.jacorb
  • org.javassist
  • org.jaxen
  • org.jboss.as.aggregate
  • org.jboss.as.appclient
  • org.jboss.as.cli
  • org.jboss.as.clustering.api
  • org.jboss.as.clustering.common
  • org.jboss.as.clustering.ejb3.infinispan
  • org.jboss.as.clustering.impl
  • org.jboss.as.clustering.infinispan
  • org.jboss.as.clustering.jgroups
  • org.jboss.as.clustering.service
  • org.jboss.as.clustering.singleton
  • org.jboss.as.clustering.web.infinispan
  • org.jboss.as.clustering.web.spi
  • org.jboss.as.cmp
  • org.jboss.as.connector
  • org.jboss.as.console
  • org.jboss.as.controller
  • org.jboss.as.controller-client
  • org.jboss.as.deployment-repository
  • org.jboss.as.deployment-scanner
  • org.jboss.as.domain-add-user
  • org.jboss.as.domain-http-error-context
  • org.jboss.as.domain-http-interface
  • org.jboss.as.domain-management
  • org.jboss.as.ee
  • org.jboss.as.ee.deployment
  • org.jboss.as.ejb3
  • org.jboss.as.embedded
  • org.jboss.as.host-controller
  • org.jboss.as.jacorb
  • org.jboss.as.jaxr
  • org.jboss.as.jaxrs
  • org.jboss.as.jdr
  • org.jboss.as.jmx
  • org.jboss.as.jpa
  • org.jboss.as.jpa.hibernate
  • org.jboss.as.jpa.hibernate
  • org.jboss.as.jpa.hibernate.infinispan
  • org.jboss.as.jpa.openjpa
  • org.jboss.as.jpa.spi
  • org.jboss.as.jpa.util
  • org.jboss.as.jsr77
  • org.jboss.as.logging
  • org.jboss.as.mail
  • org.jboss.as.management-client-content
  • org.jboss.as.messaging
  • org.jboss.as.modcluster
  • org.jboss.as.naming
  • org.jboss.as.network
  • org.jboss.as.osgi
  • org.jboss.as.platform-mbean
  • org.jboss.as.pojo
  • org.jboss.as.process-controller
  • org.jboss.as.protocol
  • org.jboss.as.remoting
  • org.jboss.as.sar
  • org.jboss.as.security
  • org.jboss.as.server
  • org.jboss.as.standalone
  • org.jboss.as.threads
  • org.jboss.as.transactions
  • org.jboss.as.web
  • org.jboss.as.webservices
  • org.jboss.as.webservices.server.integration
  • org.jboss.as.webservices.server.jaxrpc-integration
  • org.jboss.as.weld
  • org.jboss.as.xts
  • org.jboss.classfilewriter
  • org.jboss.com.sun.httpserver
  • org.jboss.common-core
  • org.jboss.dmr
  • org.jboss.ejb-client
  • org.jboss.ejb3
  • org.jboss.iiop-client
  • org.jboss.integration.ext-content
  • org.jboss.interceptor
  • org.jboss.interceptor.spi
  • org.jboss.invocation
  • org.jboss.ironjacamar.api
  • org.jboss.ironjacamar.impl
  • org.jboss.ironjacamar.jdbcadapters
  • org.jboss.jandex
  • org.jboss.jaxbintros
  • org.jboss.jboss-transaction-spi
  • org.jboss.jsfunit.core
  • org.jboss.jts
  • org.jboss.jts.integration
  • org.jboss.logging
  • org.jboss.logmanager
  • org.jboss.logmanager.log4j
  • org.jboss.marshalling
  • org.jboss.marshalling.river
  • org.jboss.metadata
  • org.jboss.modules
  • org.jboss.msc
  • org.jboss.netty
  • org.jboss.osgi.deployment
  • org.jboss.osgi.framework
  • org.jboss.osgi.resolver
  • org.jboss.osgi.spi
  • org.jboss.osgi.vfs
  • org.jboss.remoting3
  • org.jboss.resteasy.resteasy-atom-provider
  • org.jboss.resteasy.resteasy-cdi
  • org.jboss.resteasy.resteasy-jackson-provider
  • org.jboss.resteasy.resteasy-jaxb-provider
  • org.jboss.resteasy.resteasy-jaxrs
  • org.jboss.resteasy.resteasy-jsapi
  • org.jboss.resteasy.resteasy-multipart-provider
  • org.jboss.sasl
  • org.jboss.security.negotiation
  • org.jboss.security.xacml
  • org.jboss.shrinkwrap.core
  • org.jboss.staxmapper
  • org.jboss.stdio
  • org.jboss.threads
  • org.jboss.vfs
  • org.jboss.weld.api
  • org.jboss.weld.core
  • org.jboss.weld.spi
  • org.jboss.ws.api
  • org.jboss.ws.common
  • org.jboss.ws.cxf.jbossws-cxf-client
  • org.jboss.ws.cxf.jbossws-cxf-factories
  • org.jboss.ws.cxf.jbossws-cxf-server
  • org.jboss.ws.cxf.jbossws-cxf-transports-httpserver
  • org.jboss.ws.jaxws-client
  • org.jboss.ws.jaxws-jboss-httpserver-httpspi
  • org.jboss.ws.native.jbossws-native-core
  • org.jboss.ws.native.jbossws-native-factories
  • org.jboss.ws.native.jbossws-native-services
  • org.jboss.ws.saaj-impl
  • org.jboss.ws.spi
  • org.jboss.ws.tools.common
  • org.jboss.ws.tools.wsconsume
  • org.jboss.ws.tools.wsprovide
  • org.jboss.xb
  • org.jboss.xnio
  • org.jboss.xnio.nio
  • org.jboss.xts
  • org.jdom
  • org.jgroups
  • org.joda.time
  • org.junit
  • org.omg.api
  • org.osgi.core
  • org.picketbox
  • org.picketlink
  • org.python.jython.standalone
  • org.scannotation.scannotation
  • org.slf4j
  • org.slf4j.ext
  • org.slf4j.impl
  • org.slf4j.jcl-over-slf4j
  • org.w3c.css.sac
  • sun.jdk

7.4.2. 动态模块命名

所有部署都被 JBoss EAP 6 加载为模块并按照下列规格进行命名。
  1. WAR 和JAR 文件的部署是用下列格式命名的:
     deployment.DEPLOYMENT_NAME 
    例如,inventory.warstore.jar 的模块名分别是deployment.inventory.wardeployment.store.jar
  2. EAR 里的子部署是用下列格式命名的:
     deployment.EAR_NAME.SUBDEPLOYMENT_NAME 
    例如,accounts.ear 里的 reports.war 子部署的模块名将是 deployment.accounts.ear.reports.war

第 8 章 全局 Valve

8.1. 关于 Valve

Valve 是一个 Java 类,它在 Servlet 过滤器之前插入到应用程序的请求处理管道里。Valve 可以在将请求传递或执行其他处理(如验证或取消请求)之前修改请求。Valve 通常和应用程序打包在一起。
6.1.0 和以后的版本支持全局 Valve。

8.2. 关于全局 Valve

全局 Valve 是插入到应用程序的请求处理管道里的 Valve。在 JBoss EAP 6 里 Valve 可以通过打包或安装为静态模块来成为全局 Valve。全局 Valve 是在 web 子系统里配置的。
只有 6.1.0 和以后的版本支持全局 Valve。

8.3. 关于 Authenticator Valve

Authenticator Valve 是一个验证请求的凭证的 Valve。它是 org.apache.catalina.authenticator.AuthenticatorBase 的一个子类并重写了 authenticate() 方法。
它可以用于实现其他的验证模式。

8.4. 安装 Global Valve

全局 Valve 必须打包和安装为 JBoss EAP 6 里的静态模块。这个任务展示了如何安装模块。

预备条件:

  • Valve 必须已被创建且打包在 JAR 文件里。
  • 必须为这个模块创建一个 module.xml 文件。
    关于 module.xml 文件的例子,请参考 第 7.1.1 节 “模块”

过程 8.1. 安装全局模块(Global Module)

  1. 创建模块安装目录

    在应用服务器的 modules 目录里必须创建一个安装模块的目录。
    EAP_HOME/modules/system/layers/base/MODULENAME/main
    $ mkdir -P /usr/share/jboss/modules/system/layers/base/MyValveModule/main
  2. 复制文件

    复制 JAR 和 module.xml 文件到步骤 1 创建的目录里。
    $ cp MyValves.jar modules.xml /usr/share/jboss/modules/system/layers/base/MyValveModule/main
模块里声明的 Valve 类现在可在 web 子系统里进行配置。

8.5. 配置全局 Valve

全局 Valve 可以在 web 子系统里启用和配置。这是用 JBoss CLI 工具来完成的。

过程 8.2. 配置全局 Valve

  1. 启用 Valve

    使用 add 操作添加新的 Valve 条目。
    /subsystem=web/valve=VALVENAME:add(module="MODULENAME",class-name="CLASSNAME")
    您需要指定下列值:
    • VALVENAME,用来引用应用程序配置里的 valve 的名称。
    • MODULENAME,包含要配置的 Valve 的模块。
    • CLASSNAME,模块里专有 valve 的类名。
    /subsystem=web/valve=clientlimiter:add(module="clientlimitermodule",class-name="org.jboss.samplevalves.restrictedUserAgentsValve")
  2. 可选:指定参数

    如果 Valve 有配置参数,请用 add-param 操作进行指定。
    /subsystem=web/valve=testvalve:add-param(param-name="NAME", param-value="VALUE")
    /subsystem=web/valve=testvalve:add-param(
       param-name="restricteduseragents", 
       param-value="^.*MS Web Services Client Protocol.*$"
    )
Valve 已为所有部署的应用程序启用且配置好。

第 9 章 应用程序部署

9.1. 关于应用程序部署

JBoss EAP 6 带有一系列的应用程序部署和配置选项以满足管理和开发环境的需要。对于管理员而言,管理控制台和管理 CLI 提供了理想的图形化和命令行界面来管理产品环境里的应用程序部署。对于开发人员而言,应用程序部署测试选项包含了高度可配置的文件系统部署扫描器、对 IDE 如 JBoss Developer Studio 的使用及通过 Maven 进行部署和卸载。

9.2. 用管理控制台进行部署

9.2.1. 在管理控制台里管理应用程序的部署

通过管理控制台部署应用程序可为你提供易于使用的图形界面。你可以马上看到部署到服务器或组里的应用程序,而且你可以按照需要禁用或删除内容库里的应用程序。

9.2.2. 使用管理控制台部署应用程序

过程 9.1. 用管理控制台部署应用程序

  1. 进入管理控制台的 Manage Deployments 面板

    1. 从控制台的顶部选择 Runtime 标签页。
    2. 展开 DomainStandalone 菜单(如果还没展开)。
    3. 从控制台左侧的菜单里选择 Manage Deployments 选项。
  2. 部署应用程序

    部署方法会根据部署到独立服务器还是受管域而有所不同。
    • 部署到独立服务器实例

      Available Deployment Content 表显示所有可用的应用程序部署及其状态。
      1. 启用独立服务器实例里的应用程序

        点击 Deployments 表里的 Enable 按钮来启用应用程序部署。
      2. 确认

        点击 confirm 按钮来确认应用程序将在服务器实例上启用。
    • 部署到受管域

      Deployment Content 部分包含一个 Content Repository 表,它显示所有可用的应用程序部署及其状态。
      1. 启用受管域里的应用程序

        点击 Content Repository 表里的 Add 按钮。
      2. 选择服务器组

        选择您要添加应用程序的服务器组并点击 Save 按钮继续。
      3. 确认

        点击 Server Group Deployments 标签页来查看 Server Groups 表。您的应用程序现在已部署到所选的服务器组了。
结果

应用程序部署在相关的服务器或服务器组。

9.2.3. 用管理控制台下载应用程序

过程 9.2. 用管理控制台卸载应用程序

  1. 进入管理控制台的 Manage Deployments 面板

    1. 从控制台的顶部选择 Runtime 标签页。
    2. 展开 DomainStandalone 菜单(如果还没展开)。
    3. 从控制台左侧的菜单里选择 Manage Deployments 选项。
  2. 卸载应用程序

    卸载方法会根据部署到独立服务器还是受管域而有所不同。
    • 从独立服务器实例卸载应用程序

      Available Deployment Content 表显示所有可用的应用程序部署及其状态。
      1. 禁用独立服务器实例里的应用程序

        点击 Deployments 表里的 Disable 按钮来禁用应用程序部署。
      2. 确认您要禁用这个应用程序

        点击 confirm 按钮来确认应用程序将在服务器实例上禁用。
    • 从受管域里卸载

      Deployment Content 部分包含一个 Content Repository 标签页,Available Deployment Content 显示所有可用的应用程序部署及其状态。
      1. 禁用受管域里的应用程序

        点击 Server Group 标签页来查看服务器组以及部署的应用程序的状态。
      2. 选择服务器组

        点击 Server Group 表里的服务器来卸载应用程序。
      3. 从所选的服务器里禁用应用程序

        点击 disable 按钮来禁用所选服务器里的应用程序。
      4. 确认您要禁用这个应用程序

        点击 confirm 按钮来确认应用程序将在服务器实例上禁用。
      5. 对剩下的服务器组重复这些步骤

        按需要对其他服务器组重复这些步骤。Deployments 表里可以确认每个服务器组里的应用程序的状态。
结果

应用程序已从相关的服务器或服务器组里卸载。

9.3. 用管理 CLI 进行部署

9.3.1. 在管理 CLI 里管理应用程序的部署

通过管理 CLI 部署应用程序可让您用简单的命令行来创建和运行部署脚本。您可以使用脚本来配置专有的应用程序部署和管理场景。您既可以管理独立服务器实例里单个服务器的部署状态,也可以管理受管域里整个服务器网络。

9.3.2. 用管理 CLI 在受管域里部署应用程序

过程 9.3. 在受管域里部署应用程序

  • 运行 deploy 命令

    在管理 CLI 里,输入 deploy 命令及应用程序部署的位置。如要部署到所有的服务器组,可以使用 --all-server-groups 参数。
    [domain@localhost:9999 /] deploy /path/to/test-application.war --all-server-groups
    • 或者,用 --server-groups 参数定义部署的专有服务器组。
      [domain@localhost:9999 /] deploy /path/to/test-application.war --server-groups=server_group_1,server_group_2
    请注意,成功的部署不会在 CLI 里产生任何输出。
结果

指定的应用程序现在已部署在受管域的服务器组里了。

9.3.3. 用管理 CLI 卸载受管域里的应用程序

过程 9.4. 卸载受管域里的应用程序

  • 运行 undeploy 命令

    在管理 CLI 里,输入 undeploy 命令及应用程序部署的文件名。如果要从应用程序原来部署过的所有服务器组里卸载这个应用程序,可以使用 --all-relevant-server-groups 参数。
    [domain@localhost:9999 /]undeploytest-application.war--all-relevant-server-groups
    请注意,成功的卸载不会在 CLI 里产生任何输出。
结果

指定的应用程序已经卸载了。

过程 9.5. 在独立服务器里部署应用程序

  • 运行 deploy 命令

    在管理 CLI 里,输入 deploy 命令及应用程序部署的位置。
    [standalone@localhost:9999 /] deploy /path/to/test-application.war
    请注意,成功的部署不会在 CLI 里产生任何输出。
结果

指定的应用程序已部署在独立服务器里了。

过程 9.6. 卸载独立服务器里的应用程序

  • 运行 undeploy 命令

    在管理 CLI 里,输入 undeploy 命令及应用程序部署的文件名。
    [standalone@localhost:9999 /] undeploy test-application.war
    请注意,成功的卸载不会在 CLI 里产生任何输出。
结果

指定的应用程序已经卸载了。

9.4. 用部署扫描器进行部署

通过部署扫描器将应用程序部署到独立服务器实例里允许你以适合快速开发周期的方式构建和测试应用程序。你可以配置部署扫描器以适合不同应用程序类型的部署频率和行为。
总结

这个任务展示了用部署扫描器部署应用程序到独立服务器实例的方法。如 第 9.1 节 “关于应用程序部署” 所述,这个方法是为了方便开发人员而保留的,对于产品环境下的管理我们推荐管理控制台和管理 CLI 方法。

过程 9.7. 使用部署扫描器部署应用程序

  1. 复制内容到 deployment 目录

    复制应用程序文件到 EAP_HOME/standalone/deployments/ 里的 deployment 目录。
  2. 部署扫描模式

    应用程序部署分为自动和手动部署扫描模式。
    • 自动扫描

      部署扫描器获取文件夹状态的变动并创建一个 第 9.4.5 节 “对部署扫描器 Marker 文件的引用” 主题里定义的 marker 文件。
    • 手动部署

      部署扫描器需要一个 marker 文件来触发部署过程。下面的例子使用了 Unix touch 命令来创建一个新的 .dodeploy 文件。

      例 9.1. 用 touch 命令进行部署

      [user@host bin]$ touch$EAP_HOME/standalone/deployments/example.war.dodeploy
结果

应用程序文件部署到了应用服务器里。deployment 目录里创建了一个 marker 文件以表示部署成功,且应用程序在管理控制台里被标记为 Enabled

例 9.2. 在部署后 deployment 目录包含了下列内容

example.war
example.war.deployed
总结

这个任务展示了用部署扫描器卸载独立服务器实例的应用程序的方法。如 第 9.1 节 “关于应用程序部署” 所述,这个方法是为了方便开发人员而保留的,对于产品环境下的管理我们推荐管理控制台和管理 CLI 方法。

注意

部署扫描器不应该和其他用于应用程序管理的部署方法一起使用。通过管理控制台从应用服务器删除的应用程序将从 runtime 删除而不会影响 marker 文件及 deployment 目录里包含的应用程序。要最小化意外重部署或其他错误的风险,在产品环境里请使用管理 CLI 和管理控制台。

过程 9.8. 用下列方法之一卸载应用程序

  • 卸载应用程序

    有两种方法可以卸载应用程序,这取决于您是否想从 deployment 目录删除应用程序还是只修改它的部署状态。
    • 通过删除 marker 文件进行卸载

      删除已部署的应用程序的 example.war.deployed marker 文件来触发部署扫描器从 runtime 卸载应用程序。
      结果
      部署扫描器卸载应用程序并创建一个 example.war.undeployed marker 文件。应用程序仍保留在 deployment 目录里。
    • 通过删除应用程序进行卸载

      从 deployment 目录删除应用程序来触发部署扫描器从 runtime 卸载应用程序。
      结果
      部署扫描器卸载应用程序并创建一个 filename.filetype.undeployed marker 文件。应用程序现在不会出现在 deployment 目录里了。
结果

应用程序文件从应用服务器里卸载且不会出现在管理服务器的 Deployments 屏幕上了。

总结

这个任务展示了用部署扫描器重新部署应用程序到独立服务器实例的方法。如 第 9.1 节 “关于应用程序部署” 所述,这个方法是为了方便开发人员而保留的,对于产品环境下的管理我们推荐管理控制台和管理 CLI 方法。

过程 9.9. 在独立服务器里重新部署应用程序

  • 重新部署应用程序

    重新部署用部署扫描器部署的应用程序有三种可能的方法。这些方法可以触发部署扫描器来启动部署循环,您可以按个人喜好进行选择。
结果

应用程序被重新部署。

9.4.5. 对部署扫描器 Marker 文件的引用

Marker 文件

Marker 文件是部署扫描器子系统的一部分。这些文件标记独立服务器的 deployment 目录里的应用程序的状态。Marker 文件具有和应用程序相同的名称,其后缀则表示部署的状态。下表定义了每个 marker 文件的类型及响应。

例 9.4. Marker 文件示例

下面的例子展示了用于成功部署的 testapplication.war 应用程序的实例的 marker 文件。
testapplication.war.deployed
Expand
表 9.1. Marker 文件类型定义
文件名后缀 来源 描述
.dodeploy 用户生成 表示内容应该部署到 runtime 或从 runtime 卸载。
.skipdeploy 用户生成 禁用应用程序的自动部署。用作禁止展开内容的自动部署的临时方法,阻止不完整的内容进入应用环境。它可以用于压缩的内容,扫描器会检测压缩内容的进度并等待完成。
.isdeploying 系统生成 表示部署的初始化。当部署过程完成时,Marker 文件将被删除。
.deployed 系统生成 表示内容已经被部署。如果文件被删除,这些内容将被卸载。
.failed 系统生成 表示部署失败。Marker 文件包含关于失败原因的信息。如果 Marker 文件被删除,这些内容将再次对于自动部署可见。
.isundeploying 系统生成 表示对删除 .deployed 文件的响应。完成后其内容将被卸载且 marker 文件将被自动删除。
.undeployed 系统生成 表示内容已被卸载。Marker 文件的删除对内容重部署没有影响。
.pending 系统生成 表示部署说明将被发送到有检测的问题还未解决的服务器。这个 marker 文件充当全局部署 road-block。当这个条件存在时,扫描器不会指引服务器部署或卸载任何其他内容。

9.4.6. 对部署扫描器属性的引用

部署扫描器包含下列开放给管理 CLI 且可用 write-attribute 进行配置的属性。关于配置选项的更多信息,请参考 第 9.4.8 节 “用管理 CLI 配置部署扫描器”
Expand
表 9.2. 部署扫描器属性
名称 描述 类型 默认值
auto-deploy-exploded 允许自动部署展开内容而无需 .dodeploy marker 文件。我们仅推荐用于基本的部署场景,以防止在开发人员或操作系统进行修改时发生展开的应用程序的部署。 布尔值(Boolean) False
auto-deploy-xml 允许自动部署 XML 内容而无需 .dodeploy marker 文件。 布尔值(Boolean) True
auto-deploy-zipped 允许自动部署压缩内容而无需 .dodeploy marker 文件。 布尔值(Boolean) True
deployment-timeout 部署扫描器在取消部署前允许尝试部署的时间。 Long 600
path 定义要扫描的实际的文件系统路径。如果指定了 relative-to 属性,path 值将充当该目录或路径的相对路径。 String deployments
relative-to 对在服务器配置 XML 文件的 paths 部分定义的文件系统路径的引用。 String jboss.server.base.dir
scan-enabled 允许在启动时及每隔 scan-interval 自动扫描应用程序。 布尔值(Boolean) True
scan-interval 扫描资料库的时间间隔(毫秒)。小于 1 的值表示扫描器只有在启动时才操作。 Int 5000

9.4.7. 配置部署扫描器

我们可以用管理控制台或管理 CLI 配置部署扫描器。您可以创建一个新的部署扫描器或者管理现有的扫描器属性。这些包括扫描间隔、部署文件夹的位置、触发部署的应用程序文件类型。

9.4.8. 用管理 CLI 配置部署扫描器

总结

虽然有多个方法可以配置部署扫描器,管理 CLI 可以用批处理脚本或实时开放和修改属性。您可以用 read-attributewrite-attribute 全局命令行操作修改部署扫描器的行为。关于部署扫描器属性的更多信息,请参考 第 9.4.6 节 “对部署扫描器属性的引用”

部署扫描器是 JBoss EAP 6 的一个子系统,您可以在 standalone.xml 里查看它。
<subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
    <deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000"/>
</subsystem>

过程 9.10. 配置部署扫描器

  1. 确定要配置的部署扫描器属性

    通过管理 CLI 配置部署描述符要求您首先开放正确的属性名。您可以在根节点上用 read-resources 操作来实现,或者用 cd 命令来修改子节点。您也可以用 ls 命令显示这个级别的属性。
    • read-resource 操作开放部署扫描器的属性

      请使用 read-resource 操作来开放默认部署扫描器资源定义的属性。
      [standalone@localhost:9999 /]/subsystem=deployment-scanner/scanner=default:read-resource
      {
          "outcome" => "success",
          "result" => {
              "auto-deploy-exploded" => false,
              "auto-deploy-xml" => true,
              "auto-deploy-zipped" => true,
              "deployment-timeout" => 600,
              "path" => "deployments",
              "relative-to" => "jboss.server.base.dir",
              "scan-enabled" => true,
              "scan-interval" => 5000
          }
      }
      
    • ls 命令开放部署扫描器属性

      请使用 ls 命令和 -l 可选参数来显示包含子系统节点、值和类型的结果。您可以输入ls --help 来学习关于 ls 命令及其参数的更多内容。关于管理 CLI 里帮助菜单的详情,请参考 第 3.5.5 节 “用管理 CLI 获取帮助”
      [standalone@localhost:9999 /] ls -l /subsystem=deployment-scanner/scanner=default
      ATTRIBUTE            VALUE                 TYPE    
      auto-deploy-exploded false                 BOOLEAN 
      auto-deploy-xml      true                  BOOLEAN 
      auto-deploy-zipped   true                  BOOLEAN 
      deployment-timeout   600                   LONG    
      path                 deployments           STRING  
      relative-to          jboss.server.base.dir STRING  
      scan-enabled         true                  BOOLEAN 
      scan-interval        5000                  INT
      
  2. write-attribute 操作配置部署扫描器

    在您确定了要修改的属性的名称后,请使用 write-attribute 来指定属性名称和写入的新值。下面的例子都运行在子节点级别,可以通过 cd 命令访问,并开放默认扫描器节点的 Tab 完成和修改。
    [standalone@localhost:9999 /] cd subsystem=deployment-scanner/scanner=default
    
    1. 启用展开内容的自动部署

      请使用 write-attribute 命令来禁用展开的 应用程序内容的自动部署。
      [standalone@localhost:9999 scanner=default] :write-attribute(name=auto-deploy-exploded,value=true)
      {"outcome" => "success"}
      
    2. 禁用 XML 内容的自动部署

      请使用 write-attribute 命令来禁用 XML 应用程序内容的自动部署。
      [standalone@localhost:9999 scanner=default] :write-attribute(name=auto-deploy-xml,value=false)     
      {"outcome" => "success"}
      
    3. 禁用压缩内容的自动部署

      请使用 write-attribute 命令来禁用压缩的应用程序内容的自动部署。
      [standalone@localhost:9999 scanner=default] :write-attribute(name=auto-deploy-zipped,value=false)
      {"outcome" => "success"}
      
    4. 配置路径属性

      请使用 write-attribute 操作来修改路径属性,用新的路径名替换 newpathname 以被部署扫描器监控。请注意,服务器需要重启以使修改生效。
      [standalone@localhost:9999 scanner=default] :write-attribute(name=path,value=newpathname)            
      {
          "outcome" => "success",
          "response-headers" => {
              "operation-requires-reload" => true,
              "process-state" => "reload-required"
          }
      }
      
    5. 配置相对路径属性

      请使用 write-attribute 操作来修改对 XML 配置文件里路径部分定义的文件路径的相对引用。请注意,服务器将需要重启以使修改生效。
      [standalone@localhost:9999 scanner=default] :write-attribute(name=relative-to,value=new.relative.dir)
      {
          "outcome" => "success",
          "response-headers" => {
              "operation-requires-reload" => true,
              "process-state" => "reload-required"
          }
      }
      
    6. 禁用部署扫描器

      请使用 write-attribute 命令并将 scan-enabled 设为 false 来禁用部署扫描器。
      [standalone@localhost:9999 scanner=default] :write-attribute(name=scan-enabled,value=false)        
      {"outcome" => "success"}
      
    7. 修改扫描间隔

      请使用 write-attribute 操作来修改扫描间隔(5000 到 10000 毫秒)。
      [standalone@localhost:9999 scanner=default] :write-attribute(name=scan-interval,value=10000)
      {"outcome" => "success"}
      
结果

您对配置的修改已保存到部署扫描器里。

9.5. 用 Maven 进行部署

9.5.1. 用 Maven 管理应用程序部署

通过 Maven 部署应用程序允许您将部署周期合并为现有部署工作流的一部分。

9.5.2. 用 Maven 部署应用程序

总结

本节展示了用 Maven 部署应用程序的方法。下面的例子使用了 JBoss EAP 6 Quickstarts 里的 jboss-as-helloworld.war 应用程序。helloworld 项目包含了一个初始化了 jboss-as-maven-plugin 的 POM 文件。这个插件提供了在应用服务器里部署和卸载应用程序的简单操作。

过程 9.11. 用 Maven 部署应用程序

  1. 在终端会话里运行 Maven deploy 命令

    打开终端会话并进入包含 Quickstart 例程的目录里。
  2. 运行 Maven deploy 命令来部署应用程序。如果应用程序已经运行,它将被重新部署。
    [localhost]$ mvn package jboss-as:deploy
  3. 确认应用程序部署

    • 在终端窗口里查看结果

      通过在终端窗口里查看操作日志可以确认部署。

      例 9.5. 通过 Maven 确认 Helloworld 应用程序

                              
      [INFO] ------------------------------------------------------------------------
      [INFO] BUILD SUCCESSFUL
      [INFO] ------------------------------------------------------------------------
      [INFO] Total time: 3 seconds
      [INFO] Finished at: Mon Oct 10 17:22:05 EST 2011
      [INFO] Final Memory: 21M/343M
      [INFO] ------------------------------------------------------------------------
      
      
    • 在服务器终端窗口里查看结果

      部署在活动应用程序服务器实例的状态流里也可以确认。

      例 9.6. 通过应用服务器确认 Helloworld 应用程序

      17:22:04,922 INFO  [org.jboss.as.server.deployment] (pool-1-thread-3) Content added at location /home/username/EAP_HOME/standalone/data/content/2c/39607b0c8dbc6a36585f72866c1bcfc951f3ff/content
      17:22:04,924 INFO  [org.jboss.as.server.deployment] (MSC service thread 1-1) Starting deployment of "jboss-as-helloworld.war"
      17:22:04,954 INFO  [org.jboss.weld] (MSC service thread 1-3) Processing CDI deployment: jboss-as-helloworld.war
      17:22:04,973 INFO  [org.jboss.weld] (MSC service thread 1-2) Starting Services for CDI deployment: jboss-as-helloworld.war
      17:22:04,979 INFO  [org.jboss.weld] (MSC service thread 1-4) Starting weld service
      17:22:05,051 INFO  [org.jboss.web] (MSC service thread 1-2) registering web context: /jboss-as-helloworld
      17:22:05,064 INFO  [org.jboss.as.server.controller] (pool-1-thread-3) Deployed "jboss-as-helloworld.war"
结果

应用程序已部署到应用服务器里。

9.5.3. 用 Maven 卸载应用程序

总结

本节展示了用 Maven 卸载应用程序的方法。下面的例子使用了 JBoss EAP 6 Quickstarts 里的 jboss-as-helloworld.war 应用程序。helloworld 项目包含了一个初始化了 jboss-as-maven-plugin 的 POM 文件。这个插件提供了在应用服务器里部署和卸载应用程序的简单操作。

过程 9.12. 用 Maven 卸载应用程序

  1. 在终端会话里运行 Maven deploy 命令

    打开终端会话并进入包含 Quickstart 例程的目录里。

    例 9.7. 进入 helloworld 应用程序目录

    [localhost]$ cd /path/to/EAP_Quickstarts/helloworld
    
  2. 运行 Maven undeploy 命令来卸载应用程序。
    [localhost]$ mvn jboss-as:undeploy
  3. 确认应用程序已卸载

    • 在终端窗口里查看结果

      通过在终端窗口里查看操作日志可以确认卸载。

      例 9.8. 通过 Maven 确认 Helloworld 应用程序

                              
      [INFO] ------------------------------------------------------------------------
      [INFO] Building JBoss AS Quickstarts: Helloworld
      [INFO]    task-segment: [jboss-as:undeploy]
      [INFO] ------------------------------------------------------------------------
      [INFO] [jboss-as:undeploy {execution: default-cli}]
      [INFO] Executing goal undeploy for /home/username/EAP_Quickstarts/helloworld/target/jboss-as-helloworld.war on server localhost (127.0.0.1) port 9999.
      Oct 10, 2011 5:33:02 PM org.jboss.remoting3.EndpointImpl <clinit>
      INFO: JBoss Remoting version 3.2.0.Beta2
      Oct 10, 2011 5:33:02 PM org.xnio.Xnio <clinit>
      INFO: XNIO Version 3.0.0.Beta2
      Oct 10, 2011 5:33:02 PM org.xnio.nio.NioXnio <clinit>
      INFO: XNIO NIO Implementation Version 3.0.0.Beta2
      [INFO] ------------------------------------------------------------------------
      [INFO] BUILD SUCCESSFUL
      [INFO] ------------------------------------------------------------------------
      [INFO] Total time: 1 second
      [INFO] Finished at: Mon Oct 10 17:33:02 EST 2011
      [INFO] Final Memory: 11M/212M
      [INFO] ------------------------------------------------------------------------
      
      
    • 在服务器终端窗口里查看结果

      卸载在活动应用程序服务器实例的状态流里也可以确认。

      例 9.9. 通过应用服务器确认 Helloworld 应用程序

           
      17:33:02,334 INFO  [org.jboss.weld] (MSC service thread 1-3) Stopping weld service
      17:33:02,342 INFO  [org.jboss.as.server.deployment] (MSC service thread 1-3) Stopped deployment jboss-as-helloworld.war in 15ms
      17:33:02,352 INFO  [org.jboss.as.server.controller] (pool-1-thread-5) Undeployed "jboss-as-helloworld.war"
      
      
结果

从服务器服务器里卸载了应用程序。

9.6. 控制 JBoss EAP 6 里部署应用程序的顺序

JBoss EAP 6 提供了服务器启动时对部署顺序的细颗粒度控制。您可以启用多个 EAR 文件里的严格的部署顺序以及重启后的持久化顺序。

过程 9.13. 控制 JBoss EAP 6.0.X 里部署的顺序

  1. 创建在服务器启动/停止时按顺序部署和卸载应用程序的 CLI 脚本。
  2. CLI 也支持批模式,它允许您将命令和操作分组并作为一个原子单元执行。如果有一个命令或操作运行失败,该批模式里所有其他已成功执行的命令或操作将进行回滚。

过程 9.14. 控制 JBoss EAP 6.1.X 里部署的顺序

EAP 6.1.X 里有一个名为 Inter Deployment Dependencies 的新功能,它允许您在顶层部署间声明依赖关系。
  1. app.ear/META-INF 文件夹里创建一个 jboss-all.xml 文件(如果没有),这里的 app.ear 是依赖于另外一个之前部署的应用程序的归档。
  2. 如下所示,在这个文件里创建一个 jboss-deployment-dependencies 条目。请注意,在下面的列表里,framework.ear 是应该在 app.ear 之前部署的依赖关系应用程序归档。
    <jboss umlns="urn:jboss:1.0">
      <jboss-deployment-dependencies xmlns="urn:jboss:deployment-dependencies:1.0">
        <dependency name="framework.ear" />
      </jboss-deployment-dependencies>
    </jboss>
    

9.7. 部署描述符覆盖

EAP 6.1.x 里有一个新的功能,它允许您在运行时覆盖部署描述符。deployment overlay 代表了归档里的一个规则集文件,它必须被覆盖。它也提供到应该替代被覆盖文件的新文件的链接。如果在部署归档里没有出现被覆盖的文件,那它会被添加回部署里。

过程 9.15. 用管理 CLI 覆盖部署描述符

下面的步骤假设您已经有一个部署的应用程序 app.war,你想用 /home/user/web.xml 下的 web.xml 覆盖它的 WEB-INF/web.xml 文件。
  1. 添加一个部署重叠并添加内容。您可以以下列两种方式来进行:
    • 使用 DRM 树

      1. /deployment-overlay=myoverlay:add
      2. /deployment-overlay=myoverlay/content=WEB-INF\/web.xml:add(content={url=file:///home/user/web.xml})
        如果您愿意,您可以用第二个语句添加更多的内容规则。
    • 使用 convenience 模式

      deployment-overlay add --name=myoverlay --content=WEB-INF/web.xml=/home/user/web.xml
  2. 链接重叠到部署归档

    • deployment-overlay link --name=myoverlay --deployments=app.war
      你必须指定用逗号隔开的多个归档名称。
    • /deployment-overlay=myoverlay/deployment=app.war:add
      请注意,部署归档并不需要存在于服务器上。您可以指定这个名称,但不将其链接到实际的部署。
  3. 重部署应用程序

    /deployment=app.war:redeploy

第 10 章 保护 JBoss EAP 6

10.1. 关于安全子系统

安全子系统为 JBoss EAP 6 里的所有安全功能提供了基础结构。多数配置元素都几乎不需要修改。唯一需要修改的配置元素是是否使用 deep-copy-subject-mode。此外,你可以配置系统范围的安全属性。多数的配置都和安全域(Security Domain)相关。
Deep Copy 模式

如果 Deep Copy 模式被禁用(默认),复制安全数据结构会产生一个对原始结构的引用,而不是复制整个数据结构。这个行为效率更高,但在具有相同标识符的多个线程通过冲刷或登出操作清除主题时容易受数据损坏的影响。

只要被标记为可克隆的(cloneable),Deep Copy 模式会导致数据结构及相关数据的完整复制。这是更多线程安全的,但效率更低。
系统范围的安全属性

你可以设置系统范围的安全属性,它们应用在 java.security.Security 类。

安全域

安全域(Security Domain)是一系列 Java 验证和授权服务(Java Authentication and Authorization Service,JAAS)的声明式安全配置,一个或多个应用程序用它来控制验证、授权、审计和映射。有三个默认的安全域:jboss-ejb-policyjboss-web-policyother。你也可以按照应用程序的需要创建安全域。

10.2. 关于安全子系统的结构

安全子系统是在受管域或独立服务器的配置文件里配置的。多数配置元素可以用基于 web 的管理控制台或基于控制台的管理 CLI 来配置。下面是一个安全子系统配置的 XML 片段。

例 10.1. 安全子系统配置示例

<subsystem xmlns="urn:jboss:domain:security:1.2">
	<security-management>
		...
	</security-management>
	<security-domains>
        <security-domain name="other" cache-type="default">
            <authentication>
                <login-module code="Remoting" flag="optional">
                    <module-option name="password-stacking" value="useFirstPass"/>
                </login-module>
                <login-module code="RealmUsersRoles" flag="required">
                    <module-option name="usersProperties" value="${jboss.domain.config.dir}/application-users.properties"/>
                    <module-option name="rolesProperties" value="${jboss.domain.config.dir}/application-roles.properties"/>
                    <module-option name="realm" value="ApplicationRealm"/>
                    <module-option name="password-stacking" value="useFirstPass"/>
                </login-module>
            </authentication>
        </security-domain>
        <security-domain name="jboss-web-policy" cache-type="default">
            <authorization>
                <policy-module code="Delegating" flag="required"/>
            </authorization>
        </security-domain>
        <security-domain name="jboss-ejb-policy" cache-type="default">
            <authorization>
                <policy-module code="Delegating" flag="required"/>
            </authorization>
        </security-domain>
    </security-domains>
    <vault>
    	...
    </vault>
</subsystem>		
		

<security-management><subject-factory><security-properties> 元素没有出现在默认配置里。从 JBoss EAP 6.1 开始已启用了 <subject-factory><security-properties> 元素。

10.3. 配置安全子系统

你可以用管理 CLI 或基于 web 的管理控制台来配置安全子系统。
安全子系统里的每个顶级元素都包含关于安全配置不同方面的信息。关于安全子系统配置的例子,请参考 第 10.2 节 “关于安全子系统的结构”
<security-management>
这部分内容覆盖了安全子系统的高层行为。每个设置都是可选的。除了 Deep Copy 模式,须该这些设置的任何一个都是不寻常的。
Expand
选项 描述
deep-copy-subject-mode
指定是否复制或链接安全令牌以用于额外的线程安全。
authentication-manager-class-name
指定一个要使用的其他的 AuthenticationManager 实现的类名。
authorization-manager-class-name
指定一个要使用的其他的 AuthorizationManager 实现的类名。
audit-manager-class-name
指定一个要使用的其他的 AuditManager 实现的类名。
identity-trust-manager-class-name
指定一个要使用的其他的 IdentityTrustManager 实现的类名。
mapping-manager-class-name
指定一个要使用的 MappingManager 实现的类名。
<subject-factory>
主题工厂(Subject factory)控制主题实例的创建。它可以使用验证管理者来检验调用者。主题工厂的主要用途是为了 JCA 组件建立主题。你通常不需要修改它。
<security-domains>
保存多个安全域的容器元素。安全域可能包含关于验证、授权、映射、审计模块以及 JASPI 验证和 JSSE 配置的信息。你的应用程序可以指定一个安全域来管理它的安全信息。
<security-properties>
包含在 java.security.Security 类上设置的属性的名字和值。

10.4. 关于 Deep Copy Subject 模式

如果 Deep Copy 主题模式被禁用(默认),复制安全数据结构会产生一个对原始结构的引用,而不是复制整个数据结构。这个行为效率更高,但在具有相同标识符的多个线程通过冲刷或登出操作清除主题时容易受数据损坏的影响。
只要被标记为可克隆的(cloneable),Deep Copy 主题模式会导致数据结构及相关数据的完整复制。这是更多线程安全的,但效率更低。
Deep Copy Subject 模式是作为安全子系统的一部分来配置的。

10.5. 启用 Deep Copy Subject 模式

你可以通过基于 Web 的管理控制台或管理 CLI 来启用 Deep Copy 安全模式。

过程 10.1. 通过管理控制台启用 Deep Copy 安全模式

  1. 登录到管理控制台。

    管理控制台通常可通过类似 http://127.0.0.1:9990/ 的 URL 进行访问,请根据需要调整。
  2. 受管域:选择合适的配置集。

    在受管域里,安全子系统是针对每个配置集进行配置的,而且你可以在每个子系统里独立地启用或禁用 Deep Copy 安全模式。
    要选择配置集,请点击控制台右上角的 Profiles 标签,然后在左上角的 Profile 选择你要修改的配置集家。
  3. 打开 Security Subsystem 配置菜单。

    展开管理控制台右侧的 Security 菜单,然后点击 Security Subsystem 链接。
  4. 修改 deep-copy-subject-mode 值。

    点击 Edit 按钮。选定 Deep Copy Subjects: 复选框来启用 Deep Copy Subject 模式。
使用管理 CLI 启用 Deep Copy Subject 模式

如果你想通过管理 CLI 来启用这个选项,请使用下列命令。

例 10.2. 受管域

/profile=full/subsystem=security:write-attribute(name=deep-copy-subject-mode,value=TRUE)

例 10.3. 独立服务器

/subsystem=security:write-attribute(name=deep-copy-subject-mode,value=TRUE)

10.6. 安全域

10.6.1. 关于安全域

安全域是 JBoss EAP 6 安全子系统的一部分。所有的安全配置现在都由受管域的域控制器或独立服务器来集中管理了。
安全域由验证、授权、安全映射和审计的配置组成。它实现了 Java 验证和授权服务(Java Authentication and Authorization Service,JAAS) 声明式安全性。
验证指的是检验用户的身份。按照安全性术语,这个用户被称为 principal。虽然验证的授权是不同的,系统包含的许多验证模块也可以处理授权。
authorization 是一个安全策略,服务器靠它来决定已验证的用户是否具有访问系统或操作里某些权利或资源的权限。按照安全性术语,它也常被称为角色。
安全映射(Security mapping)指的是将信息传递给应用程序之前在 principal、角色或属性里添加、修改、删除信息的能力。。
审计管理者允许你配置提供者模块(provider modules)来控制报告安全事件的方式。
如果你使用安全域,你可以从应用程序删除所有的专有安全配置。这允许你集中地修改安全参数。受益于这种配置结构的一个常见场景是在测试和产品环境间移动应用程序。

10.6.2. 关于 Picketbox

Picketbox 是基础的安全框架,它为运行在 JBoss EAP 6 里的 Java 应用程序提供了验证、授权、审计和映射能力。它用单一的配置在单一的框架里提供了这些能力:

10.6.3. 关于验证

验证指的是确定一个主题并检验标识的真实性。最常见的验证机制是用户名和密码的组合。其他常见的机制使用共享密钥、智能卡或指纹。按照 Java EE 的声明安全性,成功验证的结果被称为 principal。
JBoss EAP 6 使用一个可插拔的验证模块系统,它提供灵活性以及与机构里已使用的验证系统的集成性。每个安全域都包含一个或多个配置好的验证模块。每个模块都包含其他的配置参数来自定义其行为。配置验证子系统的最简单的方法是通过基于 web 的管理控制台。
验证和授权不同,虽然他们经常联系在一起。许多包含的验证模块也可以处理授权。

10.6.4. 配置安全域的验证

要配置安全域的验证,请登录到管理控制台并遵循下列步骤。

过程 10.2. 为安全域设置验证

  1. 打开安全域的详细视图。

    点击管理控制台由上角的 Profiles 标签。在受管域里,从 Profile 视图左上角的 Profile 选择框里选择要修改的配置集。点击左侧的 Security 并点击展开菜单里的 Security Domains。点击你要编辑的安全域的 View 链接。
  2. 进入验证子系统配置。

    如果还未选择的话,点击视图顶部的 Authentication 标签。
    配置区域分成两部分:Login ModulesDetails。登录模块是配置的基本单元。安全域可以包含多个登录模块,每个都包括几个属性和选项。
  3. 添加一个验证模块。

    点击 Add 按钮来添加一个 JAAS 验证模块。输入相关的内容。Code 是模块的类名。Flags 控制模块如何和相同安全域里的其他验证模块交互。
    对标签的解释

    Java EE 6 规格提供了安全域的标签的解释。下面的列表来自 http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#AppendixA。关于更消息的信息,请参考这个文档。

    Expand
    标签 详情
    required
    登录模块是验证成功所必需的。如果成功或失败,验证都仍会继续处理登录模块列表。
    requisite
    登录模块是验证成功所必需的。如果成功,验证将继续处理登录模块列表。如果失败,控制权马上返回给应用程序(验证不会继续处理登录模块列表)。
    sufficient
    登录模块不是验证成功所必需的。如果成功,控制权马上返回给应用程序(验证不会继续处理登录模块列表)。如果失败,验证将继续处理登录模块列表。
    optional
    登录模块不是验证成功所必需的。如果成功或失败,验证都仍会继续处理登录模块列表。
    在你添加了模块时,你可以通过屏幕上的 Details 里的 Edit 按钮修改它的 CodeFlags。请确保选择了 Attributes 标签页。
  4. 可选的:添加或删除模块选项。

    如果你需要在模块里添加选项,请点击 Login Modules 列表里的条目,并在 Details 页面里选择 Module Options 标签页。点击 Add 按钮,并提供这个选项的键和值。你可以用 Remove 按钮来删除选项。
结果

你的验证模块已添加至安全域,且马上可为使用安全域的应用程序所用。

jboss.security.security_domain 模块选项

在默认情况下,安全域里定义的每个登录模块都会自动添加一个 jboss.security.security_domain 模块选项。这个选项会给检查是否只定义了已知选项的登录模块带来问题。IBM Kerberos 登录模块 com.ibm.security.auth.module.Krb5LoginModule 就是其中之一。

你可以通过在启动 JBoss EAP 时设置系统属性为 true 来禁用添加这个模块选项的行为。请添加下列内容到你的启动参数里。
-Djboss.security.disable.secdomain.option=true
你也可以用基于 web 的管理控制台来设置这个属性。在独立服务器里,你可以在配置文件的 Profile 部分来设置系统属性。在受管域里,你可以对每个服务器组设置系统属性。

10.6.5. 关于授权

授权是一个基于身份来赋予或拒绝对资源访问的机制。它作为一系列可以赋予 principal 的声明式安全角色来实现。
JBoss EAP 使用一个模块化系统来配置授权。每个安全域都可以获得一个或多个授权策略。每个策略都有一个定义自身行为的基本模块。它也可以通过特定的标记和属性来配置。配置授权子系统的最简单的方法是使用基于 web 的管理控制台。
授权不同于验证,它通常在验证之后发生。很多验证模块也可以处理授权。

10.6.6. 配置安全域里的授权

要配置安全域的授权,请登录到管理控制台并遵循下列步骤。

过程 10.3. 在安全域里设置授权

  1. 打开安全域的详细视图。

    点击管理控制台由上角的 Profiles 标签。在受管域里,从 Profile 视图左上角的 Profile 选择框里选择要修改的配置集。点击左侧的 Security 并点击展开菜单里的 Security Domains。点击你要编辑的安全域的 View 链接。
  2. 进入授权子系统配置。

    如果还未选择的话,点击视图顶部的 Authorization 标签。
    配置区域分成两部分:PoliciesDetails。登录模块是配置的基本单元。安全域可以包含几个授权策略,每个都包括几个属性和选项。
  3. 添加策略

    点击 Add 按钮来添加一个 JAAS 授权策略模块。输入相关的内容。Code 是模块的类名。Flags 控制模块如何和相同安全域里的其他授权模块交互。
    对标签的解释

    Java EE 6 规格提供了安全域的标签的解释。下面的列表来自 http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#AppendixA。关于更消息的信息,请参考这个文档。

    Expand
    标签 详情
    required
    登录模块是授权成功所必需的。如果成功或失败,授权都仍会继续处理登录模块列表。
    requisite
    登录模块是授权成功所必需的。如果成功,授权将继续处理登录模块列表。如果失败,控制权马上返回给应用程序(授权不会继续处理登录模块列表)。
    sufficient
    登录模块不是授权成功所必需的。如果成功,控制权马上返回给应用程序(授权不会继续处理登录模块列表)。如果失败,授权将继续处理登录模块列表。
    optional
    登录模块不是授权成功所必需的。如果成功或失败,授权都仍会继续处理登录模块列表。
    在你添加了模块时,你可以通过屏幕上的 Details 里的 Edit 按钮修改它的 CodeFlags。请确保选择了 Attributes 标签页。
  4. 可选的:添加、编辑或删除模块选项。

    如果你需要在模块里添加选项,点击 Login Modules 列表里的条目,并选择 Details 部分的 Module Options 标签页,并提供选项的键和值。要编辑一个已存在的选项,点击它的键来进行修改。你可以使用 Remove 按钮来删除选项。
结果

你的授权模块已添加至安全域,且马上可为使用安全域的应用程序所用。

10.6.7. 关于安全性审计

安全性审计包括触发事件,如在响应安全子系统里发生的事件而写入日志。审计机制和验证、授权、安全性映射细节都是作为安全域的一部分来配置的。
审计使用提供者模块。你可以使用内含的模块,或者实现自己的模块。

10.6.8. 配置安全审计

要配置安全域的安全审计,请登录到管理控制台并遵循下列步骤。

过程 10.4. 在安全域里设置安全审计

  1. 打开安全域的详细视图。

    点击管理控制台由上角的 Profiles 标签。在独立服务器里,标签页是 Profile。在受管域里,从 Profile 视图左上角的 Profile 选择框里选择要修改的配置集。点击左侧的 Security 并点击展开菜单里的 Security Domains。点击你要编辑的安全域的 View 链接。
  2. 进入审计子系统配置。

    如果还未选择的话,点击视图顶部的 Audit 标签。
    配置区域分成两部分:Provider ModulesDetails。提供者模块(Provider Module)是配置的基本单元。安全域可以包含多个提供者模块,每个都包括几个属性和选项。
  3. 添加一个提供者模块。

    点击 Add 按钮来添加一个提供者模块。在 Code 里输入提供者模块的类名。
    在你添加了模块时,你可以通过屏幕上的 Details 里的 Edit 按钮修改它的 Code。请确保选择了 Attributes 标签页。
  4. 检验你的模块是否可以运行

    审计模块的目的是提供一个在安全子系统里监控事件的途径。这种监控可以通过写入日志文件、电子邮件通知或其他可度量的审计机制来实现。
    例如,JBoss EAP 6 默认包含了 LogAuditProvider 模块。如果按照上面的步骤启用,这个审计模块会将安全通知写入 EAP_HOME 目录里的 log 子目录下的 audit.log 文件里。
    要检验上面的步骤是否可以在 LogAuditProvider 上下文里运行,你可以执行一个可能触发通知的动作并检查审计日志文件。
    关于安全审计提供者模块的完整列表,请参考 第 11.4 节 “包括的安全审计供应商模块”
  5. 可选的:添加、编辑或删除模块选项。

    如果你需要在模块里添加选项,点击 Modules 列表里的条目,并选择 Details 部分的 Module Options 标签页,并提供选项的键和值。要编辑一个已存在的选项,你可以使用 Remove 按钮来删除它,或者用正确的选项点击 Add 按钮再次添加它。
结果

你的安全审计模块已添加至安全域,且马上可为使用安全域的应用程序所用。

10.6.9. 关于安全性映射

安全性映射允许你在验证或授权发生后但在信息传递给应用程序之前合并验证和授权信息。其中一个例子是使用用于验证的 X509 证书,然后从证书转换 principal 为你的应用程序可以显示的逻辑名称。
你可以映射 principal(验证)、角色(授权)或凭证(非 principal 或角色的属性)。
角色映射用于在验证后对主题添加、替换或删除角色。
Principal 映射用于在验证后修改 principal。
属性映射用来从外部系统转换属性以供应用程序使用,反之亦然。

10.6.10. 在安全域里配置安全映射

要配置安全域的安全映射,请登录到管理控制台并遵循下列步骤。

过程 10.5. 在安全域里设置安全映射

  1. 打开安全域的详细视图。

    点击管理控制台由上角的 Profiles 标签。在独立服务器里,标签页是 Profile。在受管域里,从 Profile 视图左上角的 Profile 选择框里选择要修改的配置集。点击左侧的 Security 并点击展开菜单里的 Security Domains。点击你要编辑的安全域的 View 链接。
  2. 进入映射子系统配置。

    如果还未选择的话,点击视图顶部的 Mapping 标签。
    配置区域分成两部分:ModulesDetails。映射模块是配置的基本单元。安全域可以包含多个映射模块,每个都包括几个属性和选项。
  3. 添加一个模块。

    点击 Add 按钮来添加一个安全映射模块。输入模块的相关内容。Code 是模块的类名。Type 字段表示这个模块执行的映射的类型。所允许的值有 principal、role、attribute 和 credential。
    在你添加了模块时,你可以通过屏幕上的 Details 里的 Edit 按钮修改它的 CodeType。请确保选择了 Attributes 标签页。
  4. 可选的:添加、编辑或删除模块选项。

    如果你需要在模块里添加选项,点击 Modules 列表里的条目,并选择 Details 部分的 Module Options 标签页,并提供选项的键和值。要编辑一个已存在的选项,点击 Remove 标签键来删除它,并用新的值再次添加它。你可以使用 Remove 按钮来删除选项。
结果

你的安全映射模块已添加至安全域,且马上可为使用安全域的应用程序所用。

10.6.11. 在应用程序里使用安全域

概述

要在应用程序里使用安全域,首先你必须通过服务器配置文件或应用程序的描述符文件配置安全域。然后你必须添加必要的注解到使用安全域的 EJB。这个主题涵盖了在应用程序里使用安全域所需的步骤。

警告

如果应用程序不是使用验证缓存的安全域的一部分,用于该应用程序的用户验证将也可用于安全域里的其他应用程序。

过程 10.6. 配置你的应用程序以使用安全域

  1. 定义安全域

    你可以在服务器的配置文件或应用程序的描述符里定义安全域。
    • 在服务器的配置文件里配置安全域

      安全域是在服务器配置文件的 security 子系统里配置的。如果 JBoss EAP 6 实例运行在受管域里,配置文件应该是 domain/configuration/domain.xml。如果是独立服务器,则是 standalone/configuration/standalone.xml 文件。
      otherjboss-web-policyjboss-ejb-policy 都是 JBoss EAP 6 里默认提供的安全域。下面的 XML 示例是从服务器配置文件的 security 子系统里复制的。
      <subsystem xmlns="urn:jboss:domain:security:1.2">
          <security-domains>
              <security-domain name="other" cache-type="default">
                  <authentication>
                      <login-module code="Remoting" flag="optional">
                          <module-option name="password-stacking" value="useFirstPass"/>
                      </login-module>
                      <login-module code="RealmDirect" flag="required">
                          <module-option name="password-stacking" value="useFirstPass"/>
                      </login-module>
                  </authentication>
              </security-domain>
              <security-domain name="jboss-web-policy" cache-type="default">
                  <authorization>
                      <policy-module code="Delegating" flag="required"/>
                  </authorization>
              </security-domain>
              <security-domain name="jboss-ejb-policy" cache-type="default">
                  <authorization>
                      <policy-module code="Delegating" flag="required"/>
                  </authorization>
              </security-domain>
          </security-domains>
      </subsystem>
      
      你可以按需要用管理控制台或 CLI 配置其他的安全域。
    • 在应用程序的描述符文件里配置安全域

      安全域是在应用程序的 WEB-INF/jboss-web.xml 文件里的 <jboss-web> 元素的<security-domain> 子元素里指定的。下面的例子配置了一个名为 my-domain 的安全域。
      <jboss-web>
          <security-domain>my-domain</security-domain>
      </jboss-web>
      
      这只是你可以在 WEB-INF/jboss-web.xml 描述符里指定的许多设置中的一个。
  2. 在 EJB 里添加必需的注解

    你可以用 @SecurityDomain@RolesAllowed 注解在 EJB 里配置安全性。下面的 EJB 代码示例限制了具有 guest 角色的用户对 other 安全域的访问。
    package example.ejb3;
    
    import java.security.Principal;
    
    import javax.annotation.Resource;
    import javax.annotation.security.RolesAllowed;
    import javax.ejb.SessionContext;
    import javax.ejb.Stateless;
    
    import org.jboss.ejb3.annotation.SecurityDomain;
    
    /**
     * Simple secured EJB using EJB security annotations
     * Allow access to "other" security domain by users in a "guest" role.
     */
    @Stateless
    @RolesAllowed({ "guest" })
    @SecurityDomain("other")
    public class SecuredEJB {
    
       // Inject the Session Context
       @Resource
       private SessionContext ctx;
    
       /**
        * Secured EJB method using security annotations
        */
       public String getSecurityInfo() {
          // Session context injected using the resource annotation
          Principal principal = ctx.getCallerPrincipal();
          return principal.toString();
       }
    }
    关于更多的代码示例,请参考 JBoss EAP 6 Quickstarts 集里的 ejb-security quickstart,你可以在红帽的客户门户找到这些例子。

10.6.12. Java 容器授权合约(JACC)

10.6.12.1. 关于 Java 容器授权合约(JACC)
Java 容器授权合约(Java Authorization Contract for Containers,JACC)是一个定义容器和授权服务提供者之间合约的标准,它规范容器使用的提供者实现。它是由 JSR-115 定义的,你可以在 Java Community Process 网站上找到相关信息:http://jcp.org/en/jsr/detail?id=115。从 Java EE 1.3 以后,它已经是核心 Java EE 规格的一部分了。
JBoss EAP 通过安全子系统的安全性功能实现了对 JACC 的支持。
要配置 JACC,你需要用正确的模块配置你的安全域,然后修改 jboss-web.xml 来包含正确的参数。
为安全域添加 JACC 支持

要为安全域添加 JACC 支持,请添加 JACC 授权策略到安全域的授权栈里,并设置 required 标记。下面是一个带有 JACC 支持的安全域的例子。然而,安全域是在管理控制台或 CLI 里,而不是直接在 XML 里配置的。

<security-domain name="jacc" cache-type="default">
    <authentication>
        <login-module code="UsersRoles" flag="required">
        </login-module>
    </authentication>
    <authorization>
        <policy-module code="JACC" flag="required"/>
    </authorization>
</security-domain>

配置 Web 应用程序以使用 JACC

jboss-web.xml 位于你的部署的 META-INF/WEB-INF/ 目录里,且包含用 web 容器的覆盖选项和其他的 JBoss 专有的配置。要使用启用了 JACC 的安全域,你需要包括 <security-domain> 元素并设置 <use-jboss-authorization> 元素为 true。下面的应用程序是用上面的 JACC 安全域进行正确配置的。

<jboss-web>
    <security-domain>jacc</security-domain>
    <use-jboss-authorization>true</use-jboss-authorization>
</jboss-web>

配置 EJB 应用程序来使用 JACC

配置 EJB 使用安全域并使用 JACC 对于不同的 Web 应用程序是不同的。对于 EJB,你可以在 ejb-jar.xml 里为一个方法或方法组声明 method permissions。在 <ejb-jar> 元素里,任何子 <method-permission> 元素都包含关于 JACC 角色的信息。详情请参考示例配置。EJBMethodPermission 类是 Java EE 6 API 的一部分,且 http://docs.oracle.com/javaee/6/api/javax/security/jacc/EJBMethodPermission.html 里有相关的文档。

例 10.4. EJB 里的 JACC 方法权限示例

<ejb-jar>
  <method-permission>
    <description>The employee and temp-employee roles may access any method of the EmployeeService bean </description>
    <role-name>employee</role-name>
    <role-name>temp-employee</role-name>
    <method>
      <ejb-name>EmployeeService</ejb-name>
      <method-name>*</method-name>
    </method>
  </method-permission>
</ejb-jar>
	      

你也可以通过安全域约束 EJB 的验证和授权机制,就像对 Web 应用程序所做的一样。安全域在 jboss-ejb3.xml 描述符里的 <security> 子元素里声明。除了安全域以外,你也可以指定 run-as principal,它可以修改运行 EJB 的 principal。

例 10.5. EJB 里的安全域声明示例

<security>
  <ejb-name>*</ejb-name>
  <security-domain>myDomain</security-domain>
  <run-as-principal>myPrincipal</run-as-principal>
</security>


10.6.13.  Java 容器验证 SPI(JASPI)

容器安全性的 Java 验证 SPI(JASPI 或 JASPIC)是一个 Java 程序的可插拔接口。它是在 Java Community Process 的 JSR-196 里定义的。关于它的规格详情,请参考 http://www.jcp.org/en/jsr/detail?id=196
要验证 JASPI 提供者,请添加 <authentication-jaspi> 元素到你的安全域里。其配置和标准的验证模块类似,但登录模块元素包含在 <login-module-stack> 元素里。它的配置的结构是:

例 10.6. authentication-jaspi 元素的结构

<authentication-jaspi>
	<login-module-stack name="...">
	  <login-module code="..." flag="...">
	    <module-option name="..." value="..."/>
	  </login-module>
	</login-module-stack>
	<auth-module code="..." login-module-stack-ref="...">
	  <module-option name="..." value="..."/>
	</auth-module>
</authentication-jaspi>


登录模块自身也以标准验证模块完全相同的方式进行配置。
因为基于 web 的管理控制台没有开放 JASPI 验证模块的配置,在直接添加配置到 EAP_HOME/domain/configuration/domain.xmlEAP_HOME/standalone/configuration/standalone.xml 之前你需要完全停止 JBoss EAP。

10.7. 管理接口的安全性

10.7.1. 默认的用户安全性配置

简介

在 EAP 6 里,所有的管理接口都默认是有设置安全性的。这个安全性采取两种形式:

  • 本地接口通过本地客户和服务器间的 SASL 合约设置安全性。这个安全机制基于客户访问本地文件系统的能力。这是因为访问本地文件系统会允许客户添加用户或修改配置以阻挠其他安全机制。如果对文件系统的物理访问可以实现,那么其他安全机制就是多余的。这个机制以四个步骤实现:

    注意

    即使你通过 HTTP 连接本地主机,HTTP 访问仍会视作远程的。
    1. 客户发送一条消息给服务器,它包含一个用本地 SASL 机制验证的请求。
    2. 服务器生成一个一次性的令牌,将其写入到唯一的文件里,然后发送具有完整文件路径的消息给客户。
    3. 客户从文件里读取令牌并发送给服务器,检验它是否具有对文件系统的本地访问权限。
    4. 服务器验证令牌并删除这个文件。
  • 远程客户,包括本地 HTTP 客户,使用基于区的安全性。带有使用管理接口远程配置 JBoss EAP 6 权限的默认区是 ManagementRealm。我们提供了一个脚本,允许你添加用户到这个区(或者你创建的区)。请参考《JBoss EAP 6 安装指南》Getting Started 章节。对于每个用户,用户名,hased 密码,以及区都存储在文件里。
    受管域
    EAP_HOME/domain/configuration/mgmt-users.properties
    独立服务器
    EAP_HOME/standalone/configuration/mgmt-users.properties
    即使 mgmt-users.properties 的内容都是以掩码显示的,这个文件仍必须作为敏感文件对待。我们推荐将其文件权限设置为 600,这样除了文件所有者,其他人都没有读或写的权限。

10.7.2. 高级管理接口配置概述

EAP_HOME/domain/configuration/host.xmlEAP_HOME/standalone/configuration/standalone.xml 里的管理接口配置控制主机控制器进程绑定哪些网络接口,哪种管理接口是可用的,哪种类型的验证系统用来验证每个接口上的用户。本主题讨论了如何配置管理接口以适应你的运行环境。
管理子系统由包含几个可配置属性以及下面三个可配置子元素的 <management> 元素组成。首先定义安全区和转出连接,然后再将它们作为属性应用到管理接口。
  • <security-realms>
  • <outbound-connections>
  • <management-interfaces>
安全区

安全区(Security Realm)负责允许通过管理 API、管理 CLI 和基于 web 的管理控制台管理 JBoss EAP 6 的用户的验证和授权。

默认安装里有两种不同的基于文件的安全区:ManagementRealmApplicationRealm。每个安全区都使用一个 -users.properties 文件来存储用户和哈希密码,以及一个 -roles.properties 来存储用户和角色间的映射。相同也包含了对启用了 LDAP 的安全区的支持。

注意

安全区也可以用于你自己的应用程序。这里讨论的安全区是管理接口所专有的。
转出的连接

一些安全区连接至外部接口,如 LDAP 服务器。转出连接(Outbound connection)定义了如何创建这种连接。预定义的连接类型,ldap-connection,设置了连接 LDAP 服务器并验证凭证的所有必需和可选的属性。

管理接口

管理接口包含如何连接和配置 JBoss EAP 的属性。这样的信息包括命名网络接口、端口、安全区和其他关于接口的可配置信息。默认安装里包含了两个接口:

  • http-interface 是基于 web 的管理控制台的配置。
  • native-interface 是命令行管理 CLI 和类 REST 管理 API 的配置。
这三个主机管理子系统的主要可配置元素都是相关的。安全区引用转出连接,而管理接口引用安全区。
相关的信息请参考:第 10.9.1 节 “保护管理接口”

10.7.3. 关于 LDAP

轻量级目录访问协议(Lightweight Directory Access Protocol,LDAP)是一个在网络里存储和分发目录信息的协议。这个目录信息包含关于用户、硬件设备、访问角色和限制以及其他信息。
LDAP 的一些常见实现包括 OpenLDAP、Microsoft Active Directory、IBM Tivoli Directory Server、Oracle Internet Directory 等。
JBoss EAP 6 带有几个验证和授权模块,它们允许在 Web 和 EJB 应用程序里将 LDAP 服务器用于验证和授权。

10.7.4. 在管理接口里使用 LDAP 进行验证

要在管理控制台、管理 CLI 或 API 里将 LDAP 目录服务器用作验证源,你需要执行下列过程:
  1. 创建一个到 LDAP 服务器的转出连接。
  2. 创建一个启用 LDAP 的安全区。
  3. 在管理接口里引用新的安全区。
创建一个到 LDAP 服务器的转出连接

LDAP 转出连接允许下列属性:

Expand
表 10.1. LDAP 转出连接的属性
属性 要求的 描述
url
目录服务器的 URL 地址。
search-dn
授权执行搜索的用户的全限定可区分名称(Distinguished Name,DN)。
search-credentials
用户授权执行搜索的密码。
initial-context-factory
当建立连接时使用的初始上下文。默认为 com.sun.jndi.ldap.LdapCtxFactory
security-realm
为了获得建立连接时所需的已配置的 SSLContext 而引用的安全区。

例 10.7. 添加 LDAP 转出连接

这个例子用下列属性集添加了一个转出连接:
  • 搜索 DN: cn=search,dc=acme,dc=com
  • 搜索凭证: myPass
  • URL: ldap://127.0.0.1:389
第一个命令添加了安全区。
/host=master/core-service=management/security-realm=ldap_security_realm:add
第二个命令添加了 LDAP 连接。
/host=master/core-service=management/ldap-connection=ldap_connection/:add(search-credential=myPass,url=ldap://127.0.0.1:389,search-dn="cn=search,dc=acme,dc=com")
创建一个启用 LDAP 的安全区

管理接口可以针对 LDAP 服务器而不是默认的基于属性文件的安全区进行验证。LDAP 验证器将首先建立一个和远程目录服务器的连接,然后使用传入验证系统的用户名来执行搜索以找到 LDAP 记录的全限定可区分名称(Distinguished Name,DN)。新的连接将以用户的 DN 为凭证以及用户提供的密码来建立。如果这个针对 LDAP 服务器的验证成功,DN 就被证明为有效的。

LDAP 安全区需要下列配置属性和元素来执行它的功能。
connection
<outbound-connections> 里定义的连接的名称,用来连接 LDAP 目录。
base-dn
用户开始搜索的上下文的可区分的名称。
recursive
搜索是否应该在 LDAP 目录树里进行递归,或者只搜索指定的上下文。默认为 false
user-dn
保存可区分名称的用户的属性。它会被用来测试验证。默认为 dn
子元素是 username-filteradvanced-filter 中的一个。
username-filter 采用一个名为 attribute 的属性,它的值是保存用户名的 LDAP 属性的名称,如 userNamesambaAccountName
advanced-filter 采用一个名为 filter 的属性。这个属性包含以标准 LDAP 语法编写的过滤器队列。请小心地将 & 字符修改为 &amp;。下面是一个过滤器的例子:
(&(sAMAccountName={0})(memberOf=cn=admin,cn=users,dc=acme,dc=com))
After escaping the ampersand character, the filter appears as:
(&amp;(sAMAccountName={0})(memberOf=cn=admin,cn=users,dc=acme,dc=com))

例 10.8. 代表启用了 LDAP 的安全区的 XML 片段

这个例子使用了下列参数:
  • connection - ldap_connection
  • base-dn - cn=users,dc=acme,dc=com.
  • username-filter - attribute="sambaAccountName"
<security-realm name="ldap_security_realm">
   <authentication>
      <ldap connection="ldap_connection" base-dn="cn=users,dc=acme,dc=com">
         <username-filter attribute="sambaAccountName" />
      </ldap>
  </authentication>
</security-realm>	


警告

确保不允许空 LDAP 密码是很重要的;除非你故意这么做,但这是严重的安全隐患。
EAP 6.1 包含一个用于 CVE-2012-5629 的补丁,它设置 LDAP 登录模块的 allowEmptyPasswords 选项为 false(如果它还没有被设置)。在旧的版本里,这个选项应该手动进行配置。

例 10.9. 添加 LDAP 安全区

下面的命令添加了一个安全区并针对独立服务器设置其属性。
/host=master/core-service=management/security-realm=ldap_security_realm/authentication=ldap:add(base-dn="DC=mycompany,DC=org", recursive=true, username-attribute="MyAccountName", connection="ldap_connection")
应用新的安全区到管理接口里

在创建了安全区后,你需要在管理接口的配置里引用它。管理接口将使用安全区来进行 HTTP digest 验证。

例 10.10. 应用安全区到 HTTP 接口里

在配置完成后,你重启主机控制器,基于 web 的管理控制台将使用 LDAP 来验证用户。
/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=ldap-security-realm)
配置受管域成员以使用 Microsoft Active Directory 来进行验证

要配置受管域里的主机根据 Microsoft Active Directory 来验证,请按照这个过程来进行,它创建了一个安全域并使用 JAAS 验证映射角色到活动目录组。这个过程是必需的,因为 Microsoft Active Directory 允许用空的密码进行绑定。这个过程防止了在应用程序平台里使用空的密码。

在执行这个过程之前,你需要知道主机控制器的名称。这个例子假定主机控制器名为 master
  1. 添加一个名为 ldap_security_realm 的新的 <security-realm>,并配置它使用 JAAS。

    下列管理 CLI 命令添加了新的安全区并设置了它的验证机制。请按需要修改主机的名称。
    /host=master/core-service=management/security-realm=ldap_security_realm/:add
    /host=master/core-service=management/security-realm=ldap_security_realm/authentication=jaas/:add(name=managementLDAPDomain)
  2. 配置 <http-interface> 以使用这个新的安全区。

    下列管理 CLI 命令配置了 HTTP 接口。
    /host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=ldap_security_realm)
  3. 配置 JBoss EAP,在其启动参数里添加自定义的 JAAS 配置。

    编辑 EAP_HOME/bin/domain.conf 文件。搜索 HOST_CONTROLLER_JAVA_OPTS 变量。这是你添加 JBoss EAP 启动前所需的 JVM 指令的地方。下面是这个参数的默认内容的示例:
    HOST_CONTROLLER_JAVA_OPTS="$JAVA_OPTS"
    
    添加下列指令:-Djava.security.auth.login.config=/opt/jboss-eap-6.0/domain/configuration/jaas.conf"
    被编辑的行类似于:
    -Djava.security.auth.login.config=/opt/jboss-eap-6.0/domain/configuration/jaas.conf"
    
  4. 在模块选项里添加登陆模块。

    在相同的文件里,找到包含下列内容的行:
    JBOSS_MODULES_SYSTEM_PKGS="org.jboss.byteman"
    修改它为下面的样子请确保不要插入任何多余的空格。
    JBOSS_MODULES_SYSTEM_PKGS="org.jboss.byteman,com.sun.security.auth.login"
    保存并关闭 domain.conf 文件。
  5. 创建将添加至 classpath 的 JAAS 配置。

    在下列位置创建一个新的文件:EAP_HOME/domain/configuration/jaas.conf
    这个文件应该包含下列内容。请按照自己的环境编辑相关的参数。
    managementLDAPDomain {
        org.jboss.security.auth.spi.LdapExtLoginModule required
            java.naming.factory.initial="com.sun.jndi.ldap.LdapCtxFactory"
            java.naming.provider.url="ldap://your_active_directory_host:389"
            java.naming.security.authentication="simple"
            bindDN="cn=Administrator,cn=users,dc=domain,dc=your_company,dc=com"
            bindCredential="password"
            baseCtxDN="cn=users,dc=domain,dc=redhat,dc=com"
            baseFilter="(&(sAMAccountName={0})(|(memberOf=cn=Domain Guests,cn=Users,dc=domain,dc=acme,dc=com)(memberOf=cn=Domain Admins,cn=Users,dc=domain,dc=acme,dc=com)))"
            allowEmptyPasswords="false"
            rolesCtxDN="cn=users,dc=domain,dc=acme,dc=com"
            roleFilter="(cn=no such group)"
            searchScope="SUBTREE_SCOPE";
    };
    
  6. 重启 JBoss EAP,你的 HTTP 接口应该使用 LDAP 服务器来验证了。

10.7.5. 禁用 HTTP 管理接口

在受管域里,你只需要访问域控制器而不是域成员服务器上的 HTTP 接口。此外,在产品服务器上,你可能会决定禁用基于 web 的管理控制台。

注意

其他服务器,如 JBoss Operations Network,也使用 HTTP 接口来操作。如果你想使用这些服务,简单地禁用管理控制台自身就可以了,你可以设置 HTTP 接口的 console-enabled 属性为 false,而无需完全禁用这个接口。
/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=console-enabled,value=false)
要禁用对 HTTP 接口的访问,同时也禁用对基于 Web 的管理控制台的访问,你可以将 HTTP 接口一起删除。
如果你又想再次添加这个接口,下面的 JBoss CLI 命令允许你读取 HTTP 接口的当前内容。

例 10.11. 读取 HTTP 接口的配置

/host=master/core-service=management/management-interface=http-interface/:read-resource(recursive=true,proxies=false,include-runtime=false,include-defaults=true)
{
    "outcome" => "success",
    "result" => {
        "console-enabled" => true,
        "interface" => "management",
        "port" => expression "${jboss.management.http.port:9990}",
        "secure-port" => undefined,
        "security-realm" => "ManagementRealm"
    }
}
要删除 HTTP 接口,请执行下列命令:

例 10.12. 删除 HTTP 接口

/host=master/core-service=management/management-interface=http-interface/:remove
要重新启用访问,执行下列命令来重新创建带有默认值的 HTTP 接口。

例 10.13. 重新创建 HTTP 接口

/host=master/core-service=management/management-interface=http-interface:add(console-enabled=true,interface=management,port="${jboss.management.http.port:9990}",security-realm=ManagementRealm)

10.7.6. 从默认的安全区删除无提示验证

介绍

JBoss EAP 6 的默认安装包含一个用于本地管理 CLI 用户的无提示验证(Silent Authentication)方法。这允许本地用户无需用户名或密码验证就可以访问管理 CLI。启用这个功能是为了方便,并协助本地用户无需验证就可以运行管理 CLI 脚本。它是一个非常有用的功能,特别是对本地配置的访问通常也会让用户可以添加自己的细节或禁用安全检查。

如果需要更严格的安全检查,你也可以禁用对于本地用户的无提示验证。这可以通过删除配置文件里的 security-realm 部分里的 local 来实现。这适用于独立服务器的 standalone.xml 或受管域的 host.xml。你应该只在理解了对特定服务器配置的影响后才考虑删除 local 元素。
删除无提示验证的首选方法是使用管理 CLI,在下面的例子里它直接删除了 local 元素。

例 10.14. security-realm 里的 local 元素示例

<security-realms>
    <security-realm name="ManagementRealm">
        <authentication>
            <local default-user="$local"/>
            <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/>
        </authentication>
    </security-realm>
    <security-realm name="ApplicationRealm">
        <authentication>
            <local default-user="$local" allowed-users="*"/>
            <properties path="application-users.properties" relative-to="jboss.server.config.dir"/>
        </authentication>
        <authorization>
            <properties path="application-roles.properties" relative-to="jboss.server.config.dir"/>
        </authorization>
    </security-realm>
</security-realms>

过程 10.7. 从默认的安全区删除无提示验证

  • 用管理 CLI 删除无提示验证

    按要求从管理区和应用程序区删除 local 元素。
    1. 从管理区删除 local 元素。
      • 对于独立服务器

        /core-service=management/security-realm=ManagementRealm/authentication=local:remove
      • 对于受管域

        /host=HOST_NAME/core-service=management/security-realm=ManagementRealm/authentication=local:remove
    2. 从应用程序区删除 local 元素。
      • 对于独立服务器

        /core-service=management/security-realm=ApplicationRealm/authentication=local:remove
      • 对于受管域

        /host=HOST_NAME/core-service=management/security-realm=ApplicationRealm/authentication=local:remove
结果

无提示验证从 ManagementRealmApplicationRealm 里删除了。

10.7.7. 禁用对 JMX 子系统的远程访问

远程 JMX 连接性允许你触发 JDK 和应用程序管理操作。为了保护安装,请禁用这个功能。你可以通过删除远程连接配置或完全删除 JMX 子系统来实现这一点。JBoss CLI 命令引用了受管域配置里的 default 配置集。要进行修改,请修改命令的 /profile=default 部分。对于独立服务器,请完全删除命令的这个部分。

注意

在受管域里,远程连接器默认是从 JMX 子系统里删除的。如果是在部署时添加的,这个命令可供你参考。

例 10.15. 从 JMX 子系统删除远程连接器。

/profile=default/subsystem=jmx/remoting-connector=jmx/:remove

例 10.16. 删除 JMX 子系统

如果你使用了受管域,对你使用的每个配置集都运行这个命令。
/profile=default/subsystem=jmx/:remove

10.7.8. 为管理接口配置安全区

管理接口使用安全区来控制验证和对 JBoss EAP 6 的配置机制的访问。本主题展示了如何阅读和配置安全区。这些命令使用了管理 CLI。
读取安全区的配置

这个例子展示了 ManagementRealm 安全区的默认配置。它使用了一个名为 mgmt-users.properties 的文件来保存其配置信息。

例 10.17. 默认的 ManagementRealm

	/host=master/core-service=management/security-realm=ManagementRealm/:read-resource(recursive=true,proxies=false,include-runtime=false,include-defaults=true)
{
    "outcome" => "success",
    "result" => {
        "authorization" => undefined,
        "server-identity" => undefined,
        "authentication" => {"properties" => {
            "path" => "mgmt-users.properties",
            "plain-text" => false,
            "relative-to" => "jboss.domain.config.dir"
        }}
    }
}
编写安全区

下面的命令创建了一个名为 TestRealm 的安全区并为相关的配置文件设置了目录。

例 10.18. 编写安全区

/host=master/core-service=management/security-realm=TestRealm/:add/host=master/core-service=management/security-realm=TestRealm/authentication=properties/:add(path=TestUsers.properties, relative-to=jboss.domain.config.dir)

应用安全区到管理接口里

添加了安全区后,将其名称作为引用提供给管理接口。

例 10.19. 在管理接口里添加一个安全区

/host=master/core-service=management/management-interface=http-interface/:write-attribute(security-realm=TestRealm)

10.8. 用基于角色的访问控制来保护管理接口

关于基于角色的访问控制(RBAC)是一个指定管理用户的一系列权限的机制。它允许多个用户共享管理 JBoss EAP 6.2 服务器的职责而不是拥有不受限制的权限。通过对管理用户的“职责分离”,JBoss EAP 6.2 使机构可以轻易地在个人和组之间分配职责,从而避免分配不必要的权限。这既确保了服务器和数据最大可能的安全性,也提供了配置、部署和管理的灵活性。

JBoss EAP 6.2 里的关于基于角色的访问控制是通过角色权限和约束的组合来实现的。

它提供了 7 个预定义的角色,每个都有不同的固定权限。这些预定义的角色是:Monitor、Operator、Maintainer、Deployer、Auditor、Administrator 和 SuperUser。每个管理用户都分配了一个或多个角色,这些角色指定了管理服务器时用户被允许做的事情。

10.8.2. GUI 和 CLI 的基于角色的访问控制

当启用了基于角色的访问控制(RBAC)时,根据分配的角色,用户将不能运行某些操作、读取某些资源,甚至根本无法查看管理模型的某些部分。
管理控制台

在管理控制台里,根据你分配的角色的权限,有些控件和视图是禁用的(灰色)或不可见的。

如果你没有对某个资源属性的读权限,该权限将在控制台里显示为空白。例如,多数角色无法读取数据源的用户名和密码字段。

如果你没有对某个资源属性的写权限,该权限将在资源编辑表单里显示为禁用(灰色)。如果你根本没有对这个资源的写权限,那么整个编辑表单都不会出现。

如果你没有对某个资源或属性的访问权限(就是对于你的角色来说是“不可寻址的”),那它们根本不会出现在在控制台里。其中一个例子是,访问控制系统自身在默认情况下只对一些角色可见。
管理 API

启用了 RBAC 后,使用 jboss-cli.sh 工具或直接使用 API 的用户在 API 里会遇到稍许不同的行为。

无法读取的资源和属性将从结果里过滤。如果被过滤的内容是角色可以寻址的,那么它们的名称将列为结果里 response-headers 部分的 filtered-attributes。如果它们是无法被寻址的,那根本不会被列出。

试图访问不能寻址的资源将导致 "resource not found" 错误。

如果用户试图写入或读取他们可以寻址的资源但缺乏对应的读写权限,就会返回 "Permission Denied" 。

10.8.3. 支持的验证模式

基于角色的访问控制(RBAC)可以和 JBoss EAP 6.2 附带的标准验证提供者一起使用。它们是:username/passwordclient certificatelocal user
Username/Password

用户通过用户名和密码组合根据 mgmt-users.properties 文件或 LDAP 服务器来进行检验。
Client Certificate

使用信任库。
Local User

如果服务器运行在相同的服务器上,jboss-cli.sh 将自动验证为本地用户。在默认情况下,本地用户是 SuperUser 组的成员。
不管使用哪个提供者,JBoss EAP 负责将角色分配给用户。然而,当用 mgmt-users.properties 文件或 LDAP 服务器来验证时,这些系统可以提供用户组信息。JBoss EAP 也可以使用这些信息来为用户分配角色。

10.8.4. 标准角色

JBoss EAP 6 提供 7 个预定义的用户角色:Monitor、Operator、Maintainer、Deployer、Auditor、Administrator 和 SuperUser。每个角色都有不同的一套权限以用于专有的用例。Monitor, Operator, Maintainer, Administrator 和 SuperUser 都是在前者之上构建的,其权限一次递增。Auditor 和 Deployer 角色分别与 Monitor 和 Maintainer 角色类似,但都具有一些其他的特殊权限和限制。
Monitor

充当 Monitor 角色的用户具有最小的权限且只能读取服务器的当前配置和状态。这个角色是为了那些需要跟踪和报告服务器性能的用户而设计的。

Monitor 角色既不能修改服务器配置也不能访问敏感数据或操作。
Operator

Operator 角色扩展了 Monitor 角色,它添加了修改服务器的运行时状态的能力。这表示 Operator 可以重载并关闭服务器,也可以暂停和恢复 JMS 目的地。Operator 角色对于负责应用服务器的物理或虚拟主机的用户是很理想的,他们可以确保有需要时关闭和重启服务器。

Operator 角色既不能修改服务器配置也不能访问敏感数据或操作。
Maintainer

Maintainer 角色可以查看和修改运行时状态以及除了敏感数据和操作之外的所有配置。Maintainer 角色是普通用途的角色,它不能访问敏感数据和操作。Maintainer 角色赋予用户几乎完整的管理服务器的权限,但不能访问密码和其他敏感信息。

Maintainer 角色不能访问敏感数据或操作。
Administrator

Administrator 角色具有对服务器上除了审计日志系统以外的所有资源和操作的无限制的访问权限。 Administrator 是唯一(除了 SuperUser)可以访问敏感数据和操作的角色。这个角色也可以配置访问控制系统。只有处理敏感数据或配置用户和角色时才要求 Administrator 角色。

Administrator 角色不能访问审计日志系统且不能将自己修改为 Auditor 或 SuperUser 角色。
SuperUser

SuperUser 角色没有任何限制,它可以访问任何服务器的资源和操作,包括审计日志系统。这个角色等同于以前的 JBoss EAP 6 版本(6.0 和 6.1)里的管理员用户。如果禁用了 RBAC,所有的管理用户都会拥有和 SuperUser 角色相同的权限。
Deployer

Deployer 角色具有和 Monitor 相同的角色,但它可以修改部署的配置和状态以及其他启用为应用程序资源的资源类型。
Auditor

Auditor 角色具有 Monitor 角色的所有权限,它也可以查看(但不能修改)敏感数据,且具有对审计日志系统的完全权限。Auditor 是除了 SuperUser 之外唯一能够访问审计日志系统的角色。

Auditor 角色不能修改敏感数据或资源。它只有读的权限。

10.8.5. 关于角色权限

角色具有的权限定义了它能做的事情。并非每个角色都具有每个权限。值得注意的是,SuperUser 具有所有权限,而 Monitor 的权限最小。
每个权限都可以为某个类别的资源赋予读和写权限。
这些类别是:运行时状态、服务器配置、敏感数据、审计日志和访问控制系统。
表 10.2 “角色权限矩阵” 总结了每个角色权限。
Expand
表 10.2. 角色权限矩阵

Monitor

Operator

Maintainer

Deployer

Auditor

Administrator

SuperUser

读取配置和状态

X

X

X

X

X

X

X

读取敏感数据 [2]

X

X

X

修改敏感数据 [2]

X

X

读/修改审计日志

X

X

修改运行时状态

X

X

X[1]

X

X

修改持久性配置

X

X[1]

X

X

读/修改访问控制

X

X
[1] 权限限于应用程序资源。
[2] 哪些资源被当作 "敏感数据" 是使用敏感性约束来配置的。

10.8.6. 关于约束

约束(Constraint)是对于指定资源列表的访问控制配置的集合。RBAC 系统使用了约束和角色权限的组合来确定某个用户是否可以执行管理动作。

约束分成两个类别:应用程序(application)和敏感性(sensitivity)。
应用程序约束

应用程序约束定义了可以被具有部署角色的用户访问的资源和属性集合。在默认情况下,唯一被启用的应用程序约束是 core,它包含部署、部署重叠。应用程序约束也包含在 datasources、logging、mail、messaging、naming、resource-adapters 和 security 里(默认不会启用)。这些约束允许 Deployer 用户不仅可以部署应用程序,还可以配置和维护应用程序要求的资源。

应用程序约束的配置位于管理 API 里的 /core-service=management/access=authorization/constraint=application-classification
敏感性约束

敏感性约束定义了被认为是 “敏感的”的资源的集合。敏感的资源通常是某种机密的内容,如密码,或者对服务器的操作有着重大影响的东西,如网络、JVM 配置或系统属性。访问控制系统本身也被视作敏感的资源。

唯一对敏感资源具有写权限的角色是 Administrator 和 SuperUser。Auditor 角色只能读取敏感资源。其他角色都没有访问权限。

应用程序约束的配置位于管理 API 里的 /core-service=management/access=authorization/constraint=sensitivity-classification
库表达式约束

库表达式(Vault Expression)约束定义了读/写库表达式是否被视作敏感操作。在默认情况下,这两者都是敏感操作。

库表达式约束的配置位于管理 API 的 /core-service=management/access=authorization/constraint=vault-expression

目前你不能在管理控制台配置约束。

10.8.7. 关于 JMX 和基于角色的访问控制

基于角色的访问控制以三种方式应用于 JMX:
  1. JBoss EAP 6 的 Management API 开放为 JMX Management Bean。这些 Management Bean 被称为 "core mbeans",对它们的访问和过滤同底层的 Management API 是一模一样的。
  2. JMX 子系统的写权限被配置为“敏感的”。这表示只有 Administrator 和 SuperUser 角色可以修改这个子系统。而 Auditor 角色可以读取子系统的配置。
  3. 在默认情况下,部署的应用程序和服务(non-core mbeans)注册的 Management Bean 可以被管理用户访问,但只有 Maintainer、Operator、Administrator、SuperUser 角色可以写入它。

10.8.8. 配置基于角色的访问控制

10.8.8.1. RBAC 配置任务概述
启用了 RBAC 后,只有具有 Administration 或 SuperUser 角色的用户可以查看和修改访问控制系统。
管理控制台提供了下列常见 RBAC 任务的界面:
  • 查看和配置用户分配(或排斥)了哪些角色
  • 查看和配置组分配(或排斥)了哪些角色
  • 查看每个角色的组和用户成员资格。
  • 配置每个角色默认成员资格。
  • 常见具有作用域的角色
CLI 提供了对整个访问控制系统的访问。这表示在管理控制台里可以完成的任何事情都可以在这里完成,而且你可以用 CLI 执行一些访问控制系统无法完成的任务。
在 CLI 里也可以执行下列任务:
  • 启用和禁用 RBAC
  • 修改权限组合策略
  • 配置应用程序资源和资源敏感性约束
10.8.8.2. 启用基于角色的访问控制
在默认情况下,RBAC 是被禁用的。将提供者属性从 simple 修改为 rbac 就可以启用它。你可以用 jboss-cli.sh 工具来完成,或者当服务器下线时编辑服务器配置 XML 文件。如果在运行的服务器上禁用或启用 RBAC,在生效前必须重载服务器配置。
启用后,它只能由具有 Administrator 或 SuperUser 角色的用户禁用。在默认情况下,如果jboss-cli.sh 运行在和服务器相同的主机上,它是以 SuperUser 角色运行的。

过程 10.8. 启用 RBAC

  • 要用 jboss-cli.sh 启用 RBAC,请使用访问授权资源的 write-attribute 操作来设置提供者的属性为 rbac
    /core-service=management/access=authorization:write-attribute(name=provider, value=rbac)
    [standalone@localhost:9999 /] /core-service=management/access=authorization:write-attribute(name=provider, value=rbac)
    {
        "outcome" => "success",
        "response-headers" => {
            "operation-requires-reload" => true,
            "process-state" => "reload-required"
        }
    }
    [standalone@localhost:9999 /] /:reload
    {
        "outcome" => "success",
        "result" => undefined
    }
    [standalone@localhost:9999 /]
    

过程 10.9. 禁用 RBAC

  • 要用 jboss-cli.sh 禁用 RBAC,请使用访问授权资源的 write-attribute 操作来设置提供者的属性为 simple
    /core-service=management/access=authorization:write-attribute(name=provider, value=simple)
    [standalone@localhost:9999 /] /core-service=management/access=authorization:write-attribute(name=provider, value=simple)
    {
        "outcome" => "success",
        "response-headers" => {
            "operation-requires-reload" => true,
            "process-state" => "reload-required"
        }
    }
    [standalone@localhost:9999 /] /:reload
    {
        "outcome" => "success",
        "result" => undefined
    }
    [standalone@localhost:9999 /]
    
如果服务器已下线,你可以编辑 XML 配置文件来启用或禁用 RBAC。你可以找到 management 元素下的 access-control 元素里的 provider 属性,设置为 rbac 则启用, simple 则禁用 RBAC。
<management>

        <access-control provider="rbac">
            <role-mapping>
                <role name="SuperUser">
                    <include>
                        <user name="$local"/>
                    </include>
                </role>
            </role-mapping>
        </access-control>

    </management>
10.8.8.3. 修改权限组合策略
权限组合策略(Permission Combination Policy)定义了用户被分配了多个角色时如何确定权限。它可以设置为 permissiverejecting。默认选项是 permissive
当设置为 permissive 时,如果任何角色被分配给用户,那这个角色许可的动作将会被允许执行。
而当设置为 rejecting 时,如果许可某个动作的多个角色被分配给用户,那这个动作将会被允许执行。
当策略被设置为 rejecting 时,每个用户应该只分配一个角色。当策略为 rejecting 时,具有多个角色的用户将不能使用管理控制台或 jboss-cli.sh
权限组合策略是通过设置 permission-combination-policy 属性为 permissiverejecting 来配置的。这可以用 jboss-cli.sh 工具或编辑服务器配置 XML 文件(如果服务器已下线)来完成。

过程 10.10. 设置权限组合策略

  • 使用访问授权资源的 write-attribute 操作来设置 permission-combination-policy 为所需的策略名称。
    /core-service=management/access=authorization:write-attribute(name=permission-combination-policy, value=POLICYNAME)
    有效的策略名称是 rejecting 和 permissive。
    [standalone@localhost:9999 /] /core-service=management/access=authorization:write-attribute(name=permission-combination-policy, value=rejecting)
    {"outcome" => "success"}
    [standalone@localhost:9999 access=authorization] 
    
    
如果服务器已下线,你可以编辑 XML 配置文件来修改权限组合策略。为此,你需要编辑 access-control 元素的 permission-combination-policy 属性。
<access-control provider="rbac" permission-combination-policy="rejecting">
  <role-mapping>
    <role name="SuperUser">
      <include>
        <user name="$local"/>
      </include>
    </role>
  </role-mapping>
</access-control>

10.8.9. 管理角色

10.8.9.1. 关于角色成员资格

当启用了基于角色的控制(RBAC)时,管理用户被允许做的事情是由所分配的角色来决定的。JBoss EAP 6.2 使用了基于用户和组成员资格的包含(include)和排除(exclude)列表来确定用户具有哪些角色。

用户会被认为分配了角色,如果:
  1. 用户被:
    • 列在角色包含列表里,或者
    • 是列在角色包含列表里的组的成员。
  2. 用户没有被:
    • 列在角色排除列表里,或者
    • 是列在角色排除列表里的组的成员。

排除列表优先级高于包含列表。

用户和组的角色包含和排除也可以使用管理控制台和 jboss-cli.sh 工具来完成。

只有具有 SuperUser 或 Administrator 角色的用户才能执行这个配置。
10.8.9.2. 配置用户和角色的分配
包含或排除用户的角色可以通过管理控制台和 jboss-cli.sh 进行配置。本节只展示如何使用管理控制台来完成。
只有具有 SuperUser 或 Administrator 角色的用户才能执行这些配置。

在管理控制台里可通过下列步骤来配置用户和角色:
  1. 登陆到管理控制台。
  2. 点击『Administration』标签页。
  3. 展开左侧的『Access Control』并选择『Role Assignment』。
  4. 选择『USERS』标签页。
管理控制台里的用户角色管理的截屏

图 10.1. 管理控制台里的用户角色管理

过程 10.11. 为用户创建新的角色分配

  1. 登陆到管理控制台。
  2. 进入『Role Assignment』的『Users』标签页。
  3. 点击用户列表右上角的『Add』按钮。『Add User』对话框会出现。
    『Add User』对话框的截屏

    图 10.2. 『Add User』对话框

  4. 指定用户名,可选择输入区名。
  5. 选择是包含(include)还是排除(exclude)。
  6. 点击角色旁的复选框。你可以使用 Ctl 键(OSX 上的 Command 键)来选择多个选项。
  7. 点击『Save』按钮。
    保存成功后,『Add User』对话框将会关闭,用户列表将会更新以反映所作的修改。如果不成功则会显示 "Failed to save role assignment" 消息。

过程 10.12. 更新用户的角色分配

  1. 登陆到管理控制台。
  2. 进入『Role Assignment』的『Users』标签页。
  3. 从列表里选择用户。
  4. 点击『Edit』。『Selection』面板将进入编辑模式。
    『Selection』编辑视图的截屏

    图 10.3. 『Selection』面板的编辑视图

    在这里你可以添加和删除所分配或排除的角色。
    1. 要添加被分配的角色,从左侧的『Available roles』列表里进行选择并点击『Assigned roles』列表旁的右箭头。角色将从可用列表移至『Assigned roles』列表。
    2. 要删除被分配的角色,从右侧的『Assigned roles』列表里选择要删除的角色,并点击旁边的左箭头。角色将从『Assigned roles』列表移至『Available roles』列表。
    3. 要添加被排除的角色,从左侧的『Available roles』列表里进行选择并点击『Excluded roles』列表旁的右箭头。角色将从可用列表移至『Excluded roles』列表。
    4. 要删除被排除的角色,从右侧的『Excluded roles』列表里选择要删除的角色,并点击旁边的左箭头。角色将从『Excluded roles』列表移至『Available roles』列表。
  5. 点击『Save』按钮。
    成功后,编辑视图将会关闭,用户列表将会更新以反映所作的修改。如果不成功则会显示 "Failed to save role assignment" 消息。

过程 10.13. 删除用户的角色分配

  1. 登陆到管理控制台。
  2. 进入『Role Assignment』的『Users』标签页。
  3. 从列表里选择用户。
  4. 点『Remove』按钮。『Remove Role Assignment』确认框将出现。
  5. 点击『Confirm』按钮。
    成功后,用户将不会再出现在用户角色分配的列表里。

重要

从角色分配列表里删除用户并不会从系统删除这个用户,也不能保证没有角色被分配给这个用户。角色仍可能通过组成员资格分配给用户。
10.8.9.3. 用 jboss-cli.sh 配置用户角色分配
包含或排除用户的角色可以通过管理控制台和 jboss-cli.sh 进行配置。本节只展示如何使用 jboss-cli.sh 工具来完成。
映射用户/组到角色的配置位于 management API 里的 /core-service=management/access=authorization as role-mapping 元素。
只有具有 SuperUser 或 Administrator 角色的用户才能执行这些配置。

过程 10.14. 查看角色分配配置

  1. 使用 :read-children-names 操作来获取配置角色的完整列表:
    /core-service=management/access=authorization:read-children-names(child-type=role-mapping)
    [standalone@localhost:9999 access=authorization] :read-children-names(child-type=role-mapping)
    {
        "outcome" => "success",
        "result" => [
            "ADMINISTRATOR",
            "DEPLOYER",
            "MAINTAINER",
            "MONITOR",
            "OPERATOR",
            "SuperUser"
        ]
    }
    
  2. 使用指定 role-mapping 的 read-resource 操作来获取某个角色的完整细节:
    /core-service=management/access=authorization/role-mapping=ROLENAME:read-resource(recursive=true)
    [standalone@localhost:9999 access=authorization] ./role-mapping=ADMINISTRATOR:read-resource(recursive=true)
    {
        "outcome" => "success",
        "result" => {
            "include-all" => false,
            "exclude" => undefined,
            "include" => {
                "user-theboss" => {
                    "name" => "theboss",
                    "realm" => undefined,
                    "type" => "USER"
                },
                "user-harold" => {
                    "name" => "harold",
                    "realm" => undefined,
                    "type" => "USER"
                },
                "group-SysOps" => {
                    "name" => "SysOps",
                    "realm" => undefined,
                    "type" => "GROUP"
                }
            }
        }
    }
    [standalone@localhost:9999 access=authorization]
    

过程 10.15. 添加新的角色

这个过程展示了如何添加角色的 role-mapping 条目。这必须在角色可以被配置前完成。
  • 使用 add 操作来添加新的角色配置。
    /core-service=management/access=authorization/role-mapping=ROLENAME:add
    ROLENAME 是新映射使用的角色的名称。
    [standalone@localhost:9999 access=authorization] ./role-mapping=AUDITOR:add             
    {"outcome" => "success"}
    [standalone@localhost:9999 access=authorization]
    

过程 10.16. 添加包含在角色里的用户

这个过程展示了如何添加用户到角色的包含列表里。
如果角色的配置还未完成,那你必须先设置 role-mapping 条目。
  • 请使用 add 操作来添加用户到角色的包含列表里。
    /core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:add(name=USERNAME, type=USER)
    ROLENAME 是被配置的角色的名称。
    ALIAS 是这个映射的唯一名称。红帽推荐你对别名使用命名规则,如 user-USERNAME
    USERNAME 是添加到包含列表里的用户的名称。
     [standalone@localhost:9999 access=authorization] ./role-mapping=AUDITOR/include=user-max:add(name=max, type=USER)
    {"outcome" => "success"}
    [standalone@localhost:9999 access=authorization]
    

过程 10.17. 添加角色所排除的用户

这个过程展示了如何添加用户到角色的排除列表里。
如果角色的配置还未完成,那你必须先设置 role-mapping 条目。
  • 请使用 add 操作来添加用户到角色的排除列表里。
    /core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:add(name=USERNAME, type=USER)
    ROLENAME 是被配置的角色的名称。
    USERNAME 是添加到排除列表里的用户的名称。
    ALIAS 是这个映射的唯一名称。红帽推荐你对别名使用命名规则,如 user-USERNAME
    [standalone@localhost:9999 access=authorization] ./role-mapping=AUDITOR/exclude=user-max:add(name=max, type=USER)
    {"outcome" => "success"}
    [standalone@localhost:9999 access=authorization]
    

过程 10.18. 删除用户的角色包含配置

这个过程展示了如何从角色映射里删除用户包含条目。
  • 请使用 remove 操作来删除这个条目。
    /core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:remove
    ROLENAME 是被配置的角色的名称。
    ALIAS 是这个映射的唯一名称。红帽推荐你对别名使用命名规则,如 user-USERNAME
    [standalone@localhost:9999 access=authorization] ./role-mapping=AUDITOR/include=user-max:remove
    {"outcome" => "success"}
    [standalone@localhost:9999 access=authorization]
    
    从包含列表里删除用户并不会从系统删除这个用户,也不能保证角色不会被分配给这个用户。这个角色仍可能根据组成员资格分配给它。

过程 10.19. 删除用户的角色排除配置

这个过程展示了如何从角色映射里删除用户排除条目。
  • 请使用 remove 操作来删除这个条目。
    /core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:remove
    ROLENAME 是被配置的角色的名称。
    ALIAS 是这个映射的唯一名称。红帽推荐你对别名使用命名规则,如 user-USERNAME
    [standalone@localhost:9999 access=authorization] ./role-mapping=AUDITOR/exclude=user-max:remove
    {"outcome" => "success"}
    [standalone@localhost:9999 access=authorization]
    
    从排除列表里删除用户并不会从系统删除这个用户,也不能保证角色被分配给这个用户。这个角色仍可能根据组成员资格被排除。
10.8.9.4. 关于角色和用户组
使用 mgmt-users.properties 文件或 LDAP 服务器验证的用户可以是用户组的成员。用户组是可以分配给一个或多个用户的任意标签。
你可以配置 RBAC 系统根据用户所在的用户组自动分配角色给用户。它也可以根据用户组成员资格来排除用户。
当使用 mgmt-users.properties 文件时,组信息保存在 mgmt-groups.properties 文件里。当使用 LDAP 时,组信息保存在 LDAP 服务器里并由负责 LDAP 服务器的人员来维护。
10.8.9.5. 配置组角色的分配
角色可以根据用户的用户组成员资格分配给用户。
角色包含或排除组可以通过管理控制台和 jboss-cli.sh 进行配置。本节只展示如何使用管理控制台来完成。
只有具有 SuperUser 或 Administrator 角色的用户才能执行这些配置。
在管理控制台里可通过下列步骤来配置组和角色:
  1. 登陆到管理控制台。
  2. 点击『Administration』标签页。
  3. 展开左侧的『Access Control』并选择『Role Assignment』。
  4. 选择『GROUPS』标签页。
管理控制台里的组角色管理的截屏

图 10.4. 管理控制台里的组角色管理

过程 10.20. 为组创建新的角色分配

  1. 登陆到管理控制台
  2. 进入『Role Assignment』的『GROUPS』标签页。
  3. 点击用户列表右上角的『Add』按钮。『Add Group』对话框会出现。
    『Add Group』对话框的截屏

    图 10.5. 『Add Group』对话框

  4. 指定组名,可选择输入区名。
  5. 选择是包含(include)还是排除(exclude)。
  6. 点击角色旁的复选框。你可以使用 Ctl 键(OSX 上的 Command 键)来选择多个选项。
  7. 点击『Save』按钮。
    保存成功后,『Add Group』对话框将会关闭,组列表将会更新以反映所作的修改。如果不成功则会显示 "Failed to save role assignment" 消息。

过程 10.21. 更新组的角色分配

  1. 登陆到管理控制台。
  2. 进入『Role Assignment』的『GROUPS』标签页。
  3. 从列表里选择组。
  4. 点击『Edit』。『Selection』面板将进入编辑模式。
    编辑模式的『Selection』视图的截屏

    图 10.6. 『Selection』视图编辑模式

    在这里你可以添加和删除组里分配或排除的角色:
    • 要添加被分配的角色,从左侧的『Available roles』列表里进行选择并点击『Assigned roles』列表旁的右箭头。角色将从可用列表移至『Assigned roles』列表。
    • 要删除被分配的角色,从右侧的『Assigned roles』列表里选择要删除的角色,并点击旁边的左箭头。角色将从『Assigned roles』列表移至『Available roles』列表。
    • 要添加被排除的角色,从左侧的『Available roles』列表里进行选择并点击『Excluded roles』列表旁的右箭头。角色将从可用列表移至『Excluded roles』列表。
    • 要删除被排除的角色,从右侧的『Excluded roles』列表里选择要删除的角色,并点击旁边的左箭头。角色将从『Excluded roles』列表移至『Available roles』列表。
  5. 点击『Save』按钮。
    成功后,编辑视图将会关闭,组列表将会更新以反映所作的修改。如果不成功则会显示 "Failed to save role assignment" 消息。

过程 10.22. 删除组的角色分配

  1. 登陆到管理控制台。
  2. 进入『Role Assignment』的『GROUPS』标签页。
  3. 从列表里选择组。
  4. 点『Remove』按钮。『Remove Role Assignment』确认框将出现。
  5. 点击『Confirm』按钮。
    成功后,组将不会再出现在用户角色分配的列表里。
    从角色分配列表里删除组并不会从系统删除这个用户组,也不能保证没有角色被分配给这个组。每个组成员仍可能被直接分配角色。
10.8.9.6. 用 jboss-cli.sh 配置组角色
角色包含或排除组可以通过管理控制台和 jboss-cli.sh 进行配置。本节只展示如何使用 jboss-cli.sh 工具来完成。
映射用户/组到角色的配置位于 management API 里的 /core-service=management/access=authorization as role-mapping 元素。
只有具有 SuperUser 或 Administrator 角色的用户才能执行这些配置。

过程 10.23. 查看组角色分配配置

  1. 使用 read-children-names 操作来获取配置角色的完整列表:
    /core-service=management/access=authorization:read-children-names(child-type=role-mapping)
    [standalone@localhost:9999 access=authorization] :read-children-names(child-type=role-mapping)
    {
        "outcome" => "success",
        "result" => [
            "ADMINISTRATOR",
            "DEPLOYER",
            "MAINTAINER",
            "MONITOR",
            "OPERATOR",
            "SuperUser"
        ]
    }
    
  2. 使用指定 role-mapping 的 read-resource 操作来获取某个角色的完整细节:
    /core-service=management/access=authorization/role-mapping=ROLENAME:read-resource(recursive=true)
    [standalone@localhost:9999 access=authorization] ./role-mapping=ADMINISTRATOR:read-resource(recursive=true)
    {
        "outcome" => "success",
        "result" => {
            "include-all" => false,
            "exclude" => undefined,
            "include" => {
                "user-theboss" => {
                    "name" => "theboss",
                    "realm" => undefined,
                    "type" => "USER"
                },
                "user-harold" => {
                    "name" => "harold",
                    "realm" => undefined,
                    "type" => "USER"
                },
                "group-SysOps" => {
                    "name" => "SysOps",
                    "realm" => undefined,
                    "type" => "GROUP"
                }
            }
        }
    }
    [standalone@localhost:9999 access=authorization]
    

过程 10.24. 添加新的角色

这个过程展示了如何添加角色的 role-mapping 条目。这必须在角色可以被配置前完成。
  • 使用 add 操作来添加新的角色配置。
    /core-service=management/access=authorization/role-mapping=ROLENAME:add
    [standalone@localhost:9999 access=authorization] ./role-mapping=AUDITOR:add             
    {"outcome" => "success"}
    [standalone@localhost:9999 access=authorization]
    

过程 10.25. 添加包含在角色里的组

这个过程展示了如何添加组到角色的包含列表里。
如果角色的配置还未完成,那你必须先设置 role-mapping 条目。
  • 请使用 add 操作来添加组到角色的包含列表里。
    /core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:add(name=GROUPNAME, type=GROUP)
    ROLENAME 是被配置的角色的名称。
    GROUPNAME 是添加到包含列表里的组的名称。
    ALIAS 是这个映射的唯一名称。红帽推荐你对别名使用命名规则,如 group-GROUPNAME
    [standalone@localhost:9999 access=authorization] ./role-mapping=AUDITOR/include=group-investigators:add(name=investigators, type=GROUP)
    {"outcome" => "success"}
    [standalone@localhost:9999 access=authorization]
    

过程 10.26. 添加角色所排除的组

这个过程展示了如何添加组到角色的排除列表里。
如果角色的配置还未完成,那你必须先创建 role-mapping 条目。
  • 请使用 add 操作来添加组到角色的排除列表里。
    /core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:add(name=GROUPNAME, type=GROUP)
    ROLENAME 是被配置的角色的名称。
    GROUPNAME 是添加到包含列表里的组的名称。
    ALIAS 是这个映射的唯一名称。红帽推荐你对别名使用命名规则,如 group-GROUPNAME
    [standalone@localhost:9999 access=authorization] ./role-mapping=AUDITOR/exclude=group-supervisors:add(name=supervisors, type=USER)
    {"outcome" => "success"}
    [standalone@localhost:9999 access=authorization]
    

过程 10.27. 删除组的角色包含配置

这个过程展示了如何从角色映射里删除组包含条目。
  • 请使用 remove 操作来删除这个条目。
    /core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:remove
    ROLENAME 是被配置的角色的名称。
    ALIAS 是这个映射的唯一名称。红帽推荐你对别名使用命名规则,如 group-GROUPNAME
    [standalone@localhost:9999 access=authorization] ./role-mapping=AUDITOR/include=group-investigators:remove
    {"outcome" => "success"}
    [standalone@localhost:9999 access=authorization]
    
    从包含列表里删除组并不会从系统删除这个组,也不能保证角色不会被分配给这个组。这个角色仍可能分配给组里的用户。

过程 10.28. 删除组的角色排除配置

这个过程展示了如何从角色映射里删除组排除条目。
  • 请使用 remove 操作来删除这个条目。
    /core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:remove
    ROLENAME 是被配置的角色的名称。
    ALIAS 是这个映射的唯一名称。红帽推荐你对别名使用命名规则,如 group-GROUPNAME
    [standalone@localhost:9999 access=authorization] ./role-mapping=AUDITOR/exclude=group-supervisors:remove
    {"outcome" => "success"}
    [standalone@localhost:9999 access=authorization]
    
    从排除列表里删除组并不会从系统删除这个组,也不能保证角色被分配给这个组。这个角色仍可能根据组成员资格被排除。
10.8.9.7. 关于用 LDAP 进行授权和组加载

在 LDAP 目录里,有些条目用于用户帐号而有些条目用于组,并通过使用属性来进行交叉引用。有些属性是从用户帐号引用组条目,或者是组上的属性引用作为组成员的用户。在一些服务器上,这两种交叉引用的形式都存在。

用户使用简单的用户名通过服务器来验证也是很常见的,搜索组成员信息取决于使用的目录服务器。你可以使用简单名称来执行搜索,也可以用目录里的用户条目的标识名来执行。

用户连接服务器的验证步骤总是先发生的,一旦它已经决定用户成功验证,服务器将开始加载用户组。因为验证和授权步骤都使用到 LDAP 服务器的连接,安全区包含一个优化办法,也就是任何用于验证的连接都将被组加载步骤重用。如下面的配置步骤所展示的,你可以在授权部分定义角色来将用户的简单名称转换为标识名,这可能复制在验证步骤发生的搜索,所以,如果用户名到标识名的搜索已被执行,那么这个搜索的结果就可以被缓存和重用而无需再次进行搜索。
<authorization>
    <ldap connection="...">
       <username-to-dn> <!-- OPTIONAL -->
           <!-- Only one of the following. -->
           <username-is-dn />
           <username-filter base-dn="..." recursive="..." user-dn-attribute="..." attribute="..." />
           <advanced-filter base-dn="..." recursive="..." user-dn-attribute="..." filter="..." />
        </username-to-dn>
       <group-search group-name="..." iterative="..." group-dn-attribute="..." group-name-attribute="..." >
           <!-- One of the following -->
           <group-to-principal base-dn="..." recursive="..." search-by="...">
               <membership-filter principal-attribute="..." />
           </group-to-principal>
           <principal-to-group group-attribute="..." />
       </group-search>
    </ldap>
</authorization>

重要

有些例子里的属性是用默认值设置的,在此出现的目的是为了说明而已。当服务器进行持久化时,这些包含默认值的属性将从配置里删除。
username-to-dn

如上所述,有时候你需要在授权配置里定义如何从被验证的用户的用户名映射到 LDAP 目录里条目的标识名。username-to-dn 元素是关于它的定义的,只有下列两者都为 true 才要求定义这个元素:
  • 验证步骤不是通过 LDAP 进行的。
  • 组搜索在搜索过程中使用标识名。

请注意,当你阅读下面的例子时,你会觉得其验证配置是重复的,确实是这样 - 如果你只使用 LDAP 进行验证,那这并非必需的,因为将在验证过程中获取标识名。
1:1 username-to-dn

这个是最基本的配置形式,用于指定远程用户输入的用户名实际上是标识名。
<username-to-dn>
   <username-is-dn />
</username-to-dn>

因为这是定义的 1:1 的映射,所以没有其他可能的配置。
username-filter

下一个选项和上面验证步骤描述的选项非常类似,它简单地按照提供的用户名进行搜索。
<username-to-dn>
    <username-filter base-dn="dc=people,dc=harold,dc=example,dc=com" recursive="false" attribute="sn" user-dn-attribute="dn" />
</username-to-dn>

可以在这里设置的属性是:
  • base-dn: 开始搜索的上下文的标识名。
  • recursive:搜索是否将扩展到子上下文。默认值为 false
  • attribute:根据提供的用户名尝试和匹配的用户条目的属性。默认值为 uid
  • user-dn-attribute:为获得用户标识名而读取的属性。默认值为 dn
advanced-filter

这个最后的选项指定了高级过滤器,和验证部分一样,这是使用自定义过滤器来定位用户标识名的机会。
<username-to-dn>
    <advanced-filter base-dn="dc=people,dc=harold,dc=example,dc=com" recursive="false" filter="sAMAccountName={0}" user-dn-attribute="dn" />
</username-to-dn>

对应 username-filter 的属性的默认值都是一样的,这里不再列出。新的属性是:
  • filter:用于搜索用户条目的过滤器,用户名将在占位符 {0} 里替换。

重要

XML 格式必须保持有效,定义过滤器来确保特殊字符(如 &)的正确格式。例如,对于 & 字符是 &amp;
组搜索

如上面所描述的,在搜索组成员资格信息时你可以使用两种风格。第一种是用户条目包含引用用户所属组的属性。第二种风格是组包含引用用户条目的属性。

当可以选择风格时,红帽推荐引用所用组的用户条目的配置。这是因为用这个方法时组信息可以通过读取已知标识名来加载而无需执行任何搜索。另外一个方法则要求额外的搜索来确定引用用户的组。

在描述配置之前,这里有几个 LDIF 例子来进行解释。

例 10.20. Principal to Group - LDIF 示例。

这个例子展示了用户 TestUserOne,它是 GroupOne 的成员,而 GroupOne 也是 GroupFive 的成员。通过属性 memberOf 展示了组成员资格,它被设置为用户(或组)所属的组的标识名。

这里没有展示的是用户可能具有多个 memberOf 的属性集,每个都对应该用户所属的组。
dn: uid=TestUserOne,ou=users,dc=principal-to-group,dc=example,dc=org
objectClass: extensibleObject
objectClass: top
objectClass: groupMember
objectClass: inetOrgPerson
objectClass: uidObject
objectClass: person
objectClass: organizationalPerson
cn: Test User One
sn: Test User One
uid: TestUserOne
distinguishedName: uid=TestUserOne,ou=users,dc=principal-to-group,dc=example,dc=org
memberOf: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=org
memberOf: uid=Slashy/Group,ou=groups,dc=principal-to-group,dc=example,dc=org
userPassword:: e1NTSEF9WFpURzhLVjc4WVZBQUJNbEI3Ym96UVAva0RTNlFNWUpLOTdTMUE9PQ==

dn: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=org
objectClass: extensibleObject
objectClass: top
objectClass: groupMember
objectClass: group
objectClass: uidObject
uid: GroupOne
distinguishedName: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=org
memberOf: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=org

dn: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=org
objectClass: extensibleObject
objectClass: top
objectClass: groupMember
objectClass: group
objectClass: uidObject
uid: GroupFive
distinguishedName: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=org

例 10.21. Group to Principal - LDIF 示例

这个例子展示了相同的用户 TestUserOne,它是 GroupOne 的成员(反之也是 GroupFive 的成员)- 然而在这个例子里,它是一个用于交叉引用的组到用户的属性 uniqueMember

用于组成员资格交叉引用的属性可以重复,如果你查看 GroupFive,那里也有一个没有显示在这里的对其他用户 TestUserFive 的引用。
dn: uid=TestUserOne,ou=users,dc=group-to-principal,dc=example,dc=org
objectClass: top
objectClass: inetOrgPerson
objectClass: uidObject
objectClass: person
objectClass: organizationalPerson
cn: Test User One
sn: Test User One
uid: TestUserOne
userPassword:: e1NTSEF9SjR0OTRDR1ltaHc1VVZQOEJvbXhUYjl1dkFVd1lQTmRLSEdzaWc9PQ==

dn: uid=GroupOne,ou=groups,dc=group-to-principal,dc=example,dc=org
objectClass: top
objectClass: groupOfUniqueNames
objectClass: uidObject
cn: Group One
uid: GroupOne
uniqueMember: uid=TestUserOne,ou=users,dc=group-to-principal,dc=example,dc=org

dn: uid=GroupFive,ou=subgroups,ou=groups,dc=group-to-principal,dc=example,dc=org
objectClass: top
objectClass: groupOfUniqueNames
objectClass: uidObject
cn: Group Five
uid: GroupFive
uniqueMember: uid=TestUserFive,ou=users,dc=group-to-principal,dc=example,dc=org
uniqueMember: uid=GroupOne,ou=groups,dc=group-to-principal,dc=example,dc=org
通用组搜索

通过上面例子里展示的两种方法,我们知道首先需要定义两者共用的属性。
<group-search group-name="..." iterative="..." group-dn-attribute="..." group-name-attribute="..." >
    ...
</group-search>
  • group-name:这个属性用来指定用于作为用户所属组列表返回的组名的格式。这可以是组名的简单格式或者是组的标识名,如果标识名是必需的,那这个属性可以设置为 DISTINGUISHED_NAME。默认值是 SIMPLE
  • iterative:这个属性用来指定在确定用户所属的组之后是否应该根据组所属的组迭代地进行搜索。如果启用了迭代搜索,那么我们将继续搜索,直到到达不是成员的组或检测到循环。它的默认值为 false

循环的组成员并不是一个问题。我们保存了每次搜索的记录来防止已搜索过的组被再次搜索。

重要

为了迭代式搜索能正常进行,组条目需要和用户条目一致,也就是使用相同的方法来确定用户所属的组和确定组所属组。但对于组到组的成员关系,如果用于交叉引用的属性或者引用方向有改动,那这就无法实现了。
  • group-dn-attribute:组条目上的哪个属性是其标识名。默认为 dn
  • group-name-attribute:组条目上的哪个属性是其简单名。默认为 uid

例 10.22. Principal to Group 配置示例

基于上面的 LDIF 例子,下面是一个循环加载用户组的配置示例,用来进行交叉引用的属性是用户的 memberOf
<authorization>
    <ldap connection="LocalLdap">
        <username-to-dn>
            <username-filter base-dn="ou=users,dc=principal-to-group,dc=example,dc=org" recursive="false" attribute="uid" user-dn-attribute="dn" />
        </username-to-dn>
        <group-search group-name="SIMPLE" iterative="true" group-dn-attribute="dn" group-name-attribute="uid">
            <principal-to-group group-attribute="memberOf" />
        </group-search>
    </ldap>
</authorization>

这个配置最重要的方面是已添加了带有单个属性的 principal-to-group 元素。
  • group-attribute

例 10.23. Group to Principal 配置示例

这个例子展示了一个对上面的 group to principal LDIF 例子的迭代搜索。
<authorization>
      <ldap connection="LocalLdap">
          <username-to-dn>
              <username-filter base-dn="ou=users,dc=group-to-principal,dc=example,dc=org" recursive="false" attribute="uid" user-dn-attribute="dn" />
          </username-to-dn>
          <group-search group-name="SIMPLE" iterative="true" group-dn-attribute="dn" group-name-attribute="uid">
              <group-to-principal base-dn="ou=groups,dc=group-to-principal,dc=example,dc=org" recursive="true" search-by="DISTINGUISHED_NAME">
                  <membership-filter principal-attribute="uniqueMember" />
              </group-to-principal>
          </group-search>
      </ldap>
  </authorization>

在这里添加了 group-to-principal 元素,这个元素用来定义引用用户条目的组搜索如何只执行,它将设置下列属性:
  • base-dn: 开始搜索的上下文的标识名。
  • recursive:是否搜索子上下文。默认为 false
  • search-by:在搜索里使用的角色名称的格式。有效值是 SIMPLEDISTINGUISHED_NAME。默认值为 DISTINGUISHED_NAME

group-to-principal 元素里有一个定义交叉引用的 membership-filter 元素。
  • principal-attribute:引用用户条目的组条目上的属性名称。默认值为 member
10.8.9.8. 关于带作用域的角色

带作用域的角色(Scoped Role)是用户定义的角色,它赋予标准角色中一个角色的权限,但只用于一个或多个指定的服务器组或主机。带作用域的角色允许按需要赋予管理用户限于某些服务器组或主机的权限。

带作用域的角色可以由具有 Administrator 或 SuperUser 角色的用户来创建。

它们是由 5 个特征定义的:
  1. 唯一的名字。
  2. 基于那些标准角色。
  3. 是否应用在服务器组或主机上。
  4. 所限的服务器组或主机的列表。
  5. 是否自动包括所有用户。默认为 false。

创建之后,带作用域的角色可以和标准角色一样分配给用户和组。

创建带作用域的角色并不意味着要定义新的权限。带作用域的角色只能用来在有限的作用域李应用现存角色的权限。例如,你可以根据限于单个服务器组的 Deployer 角色创建带作用域的角色。

角色只可以限于两个作用域,主机和服务器组。
作用域为主机的角色

作用域为主机的角色将它的权限限制到一个或多个主机。这意味着为相关的 /host=*/ 资源树提供了访问权限但其他主机所专有的资源是隐藏的。
作用域为服务器组的角色

作用域为服务器组的角色限制了该角色的权限到一个或多个服务器组。此外,角色权限将应用于和指定的服务器组相关联的配置集、套接字绑定组、服务器配置和服务器资源。和这个服务器组逻辑上不关联的资源的任何子资源对于用户来说都是不可见的。

作用域为主机和服务器组的角色都具有受管域配置的其他部分的 Monitor 角色的权限。
10.8.9.9. 创建带作用域的角色

带作用域的角色(Scoped Role)是用户定义的角色,它赋予标准角色中一个角色的权限,但只用于一个或多个指定的服务器组或主机。本节将展示如何创建带作用域的角色。

只有具有 SuperUser 或 Administrator 角色的用户才能执行这些配置。

在管理控制台里可通过下列步骤来配置带作用域的角色:
  1. 登录到管理控制台
  2. 点击 Administration 标签页
  3. 展开左侧的 Access Control 并选择 Role Assignment
  4. 选择 ROLES 标签页,然后选择里面的 Scoped Roles 标签页。
Scoped Role Configuration in the Management Console

图 10.7. 在管理控制台里配置带作用域的角色

管理控制台的 Scoped Roles fen 部分由两个主要区域组成,包含当前配置的带作用域的角色的表,以及显示表里当前别选择的角色细节。
下面的过程展示了如何配置带作用域的角色。

过程 10.29. 添加新的带作用域的角色

  1. 登录到管理控制台
  2. 导航至 Roles 标签页的 Scoped Roles 区域。
  3. 点击 Add 按钮。Add Scoped Role 对话框将会出现。
    Add Scoped Role Dialog

    图 10.8. Add Scoped Role 对话框

  4. 指定下列细节:
    • Name,新的带作用域的角色的唯一名称。
    • Base Role,这个角色的权限所基于的角色。
    • Type,这个角色是否将被限于主机或服务器组。
    • Scope,这个角色所限于的主机或服务器组列表。可以选择多重条目。
    • Include All,这个角色是否自动包含所有的用户。默认为 no。
  5. 点击 Save 按钮,对话框将关闭且新创建的角色将出现在表里。

过程 10.30. 编辑带作用域的角色

  1. 登录到管理控制台
  2. 导航至 Roles 标签页的 Scoped Roles 区域。
  3. 点击你要编辑的带作用域的角色。这个角色的细节将出现在表下面的 Selection 面板上。
    Role Selected

    图 10.9. 选择的角色

  4. 点击 Selection 面板上的 Edit 链接。Selection 面板将进入编辑模式。
    Selection Panel in Edit Mode

    图 10.10. 处于编辑模式的 Selection 面板

  5. 更新你要修改的细节并点击 Save 按钮。Selection 面板将回到之前的状态。Selection 面板和表都会显示最近更新的细节。

过程 10.31. 查看 Scoped Role 成员

  1. 登录到管理控制台
  2. 导航至 Roles 标签页的 Scoped Roles 区域。
  3. 点击表里你要查看成员的带作用域的角色,然后点击 Members 按钮。Members of role 对话框将出现。它将显示这个角色包含或排斥的用户和组。
    Role Membership Dialog

    图 10.11. Role Membership 对话框

  4. 当你已经完成查看这些信息后请点击 Done 按钮。

过程 10.32. 删除带作用域的角色

重要

如果用户或组被分配至某个角色,这个角色就不能被删除。你需要先删除角色分配。
  1. 登录到管理控制台
  2. 导航至 Roles 标签页的 Scoped Roles 区域。
  3. 选择表里要删除的带作用域的角色。
  4. 点击 Remove 按钮。Remove Scoped Role 对话框将出现。
  5. 点击 Confirm 按钮。对话框将关闭且角色会被删除。

10.8.10. 配置约束

10.8.10.1. 配置 Sensitivity 约束

每个敏感性约束(Sensitivity Constraint)都定义了被认为是 “敏感的”的资源的集合。敏感的资源通常是某种机密的内容,如密码,或者对服务器的操作有着重大影响的东西,如网络、JVM 配置或系统属性。访问控制系统本身也被视作敏感的资源。资源敏感性限制了哪些角色可以读、写或寻址专门的资源。

应用程序约束的配置位于管理 API 里的 /core-service=management/access=authorization/constraint=sensitivity-classification

在管理模型内部,每个 Sensitivity 约束都被标识为类别(classification)。这些类别被分组为类型(types)。有 39 种类别被分组成 13 个类型。

要配置 Sensitivity 约束,请使用 write-attribute 操作来设置 configured-requires-readconfigured-requires-writeconfigured-requires-addressable 属性。要使该类型的操作成为敏感的,请将其设置为 false。在默认情况下,它们不会被设置而使用 default-requires-readdefault-requires-writedefault-requires-addressable 的值。一旦配置的属性被设置,它将替代默认值。默认值不能被修改。

例 10.24. 使读取系统属性成为敏感性操作

[domain@localhost:9999 /] cd /core-service=management/access=authorization/constraint=sensitivity-classification/type=core/classification=system-property
[domain@localhost:9999 classification=system-property] :write-attribute(name=configured-requires-read, value=true)
{
    "outcome" => "success",
    "result" => undefined,
    "server-groups" => {"main-server-group" => {"host" => {"master" => {
        "server-one" => {"response" => {"outcome" => "success"}},
        "server-two" => {"response" => {"outcome" => "success"}}
    }}}}
}
[domain@localhost:9999 classification=system-property] :read-resource
{
    "outcome" => "success",
    "result" => {
        "configured-requires-addressable" => undefined,
        "configured-requires-read" => true,
        "configured-requires-write" => undefined,
        "default-requires-addressable" => false,
        "default-requires-read" => false,
        "default-requires-write" => true,
        "applies-to" => {
            "/host=master/system-property=*" => undefined,
            "/host=master/core-service=platform-mbean/type=runtime" => undefined,
            "/server-group=*/system-property=*" => undefined,
            "/host=master/server-config=*/system-property=*" => undefined,
            "/host=master" => undefined,
            "/system-property=*" => undefined,
            "/" => undefined
        }
    }
}
[domain@localhost:9999 classification=system-property]

表 10.3 “Sensitivity 约束配置结果” 总结了哪些角色能够执行哪些操作所取决的配置。
Expand
表 10.3. Sensitivity 约束配置结果
requires-read requires-write requires-addressable

true

读操作是敏感的。

只有 Auditor, Administrator 和 SuperUser 可以读。

写操作是敏感的。

只有 Administrator 和 SuperUser 可以写

寻址(Addressing)是敏感的。

只有 Auditor, Administrator 和 SuperUser 可以寻址。

false

读操作是非敏感的。

任何管理用户都可以读。

写操作是非敏感的。

只有 Maintainer, Administrator 和 SuperUser 可以写。如果这个约束是一个应用程序资源的话,Deployers 也可以写。

寻址(Addressing)是非敏感的。

任何管理用户都可以寻址。
10.8.10.2. 配置应用程序资源约束

每个应用程序资源约束都定义了一系列通常和应用程序及服务部署相关联的资源、属性和操作。当启用了应用程序资源约束时,具有 Deployer 角色的管理用户会被赋予访问资源的权限。

应用程序约束配置位于 /core-service=management/access=authorization/constraint=application-classification/ 里的管理模型。

在管理模型内部,每个应用程序资源约束都被标识为类别(classification)。这些类别被分组为类型(types)。有 14 种类别被分组成 8 个类型。每个类别都有一个 applies-to 元素,它是一个类别配置应用的资源路径模式的列表。

在默认情况下,唯一启用的应用程序资源类别是 core。Core 包含部署、部署重叠和部署操作。

要启用应用程序资源,请使用 write-attribute 操作来设置 configured-application attributetrue。要禁用应用程序资源,请设置这个属性为 false。在默认情况下,这些属性没被设置且使用了 default-application 属性的值。这个默认值不能被修改。

例 10.25. 启用 logger-profile 应用程序资源归类

[domain@localhost:9999 /] cd /core-service=management/access=authorization/constraint=application-classification/type=logging/classification=logging-profile
[domain@localhost:9999 classification=logging-profile] :write-attribute(name=configured-application, value=true)
{
    "outcome" => "success",
    "result" => undefined,
    "server-groups" => {"main-server-group" => {"host" => {"master" => {
        "server-one" => {"response" => {"outcome" => "success"}},
        "server-two" => {"response" => {"outcome" => "success"}}
    }}}}
}
[domain@localhost:9999 classification=logging-profile] :read-resource 
{
    "outcome" => "success",
    "result" => {
        "configured-application" => true,
        "default-application" => false,
        "applies-to" => {"/profile=*/subsystem=logging/logging-profile=*" => undefined}
    }
}
[domain@localhost:9999 classification=logging-profile]

重要

应用程序资源约束应用域所有匹配它的配置的资源。例如,只将 Deployer 用户权限赋予一个数据源资源而不是另外一个是不可能的。如果需要这种级别的分离,那么我们推荐在其他的服务器组里配置资源并为每个组创建不同作用域的 Deployer 角色。
10.8.10.3. 配置 Vault 表达式约束

在默认情况下,读和写 Vault 表达式是敏感操作。配置 Vault 表达式约束允许你设置这两个操作为非敏感的。修改这个约束允许更多的角色读和写 Vault 表达式。

Vault 表达式约束的配置位于 /core-service=management/access=authorization/constraint=vault-expression 上的管理模型里。

要配置 Vault 表达式,请使用 write-attribute 操作来设置 configured-requires-writeconfigured-requires-read 的属性为 truefalse。在默认情况下,它们不会被设置而使用 default-requires-readdefault-requires-write 的值。默认值不能被修改。

例 10.26. 使写入 Vault 表示成为非敏感操作

[domain@localhost:9999 /] cd /core-service=management/access=authorization/constraint=vault-expression
[domain@localhost:9999 constraint=vault-expression] :write-attribute(name=configured-requires-write, value=false)
{
    "outcome" => "success",
    "result" => undefined,
    "server-groups" => {"main-server-group" => {"host" => {"master" => {
        "server-one" => {"response" => {"outcome" => "success"}},
        "server-two" => {"response" => {"outcome" => "success"}}
    }}}}
}
[domain@localhost:9999 constraint=vault-expression] :read-resource
{
    "outcome" => "success",
    "result" => {
        "configured-requires-read" => undefined,
        "configured-requires-write" => false,
        "default-requires-read" => true,
        "default-requires-write" => true
    }
}
[domain@localhost:9999 constraint=vault-expression]

表 10.4 “Vault 表达式约束配置结果” 总结了哪些角色能够读取和写入 Vault 表达式所取决的配置。
Expand
表 10.4. Vault 表达式约束配置结果
requires-read requires-write

true

读操作是敏感的。

只有 Auditor, Administrator 和 SuperUser 可以读。

写操作是敏感的。

只有 Administrator 和 SuperUser 可以写。

false

读操作是不敏感的。

所有管理用户都可以读。

写操作是不敏感的。

Monitor, Administrator 和 SuperUser 都可以写。如果 Vault 表达式是一个应用程序资源的话,Deployers 也可以写。

10.8.11. 约束引用

10.8.11.1. 应用程序资源约束引用

类型:core

类别:deployment-overlay
  • 默认值:true
    Expand
    PATH 属性 操作

    /deployment-overlay=*

    /deployment=*

    /

    upload-deployment-stream, full-replace-deployment, upload-deployment-url, upload-deployment-bytes

类型:datasources

类别:datasource
  • 默认值:false
    Expand
    PATH 属性 操作

    /deployment=*/subdeployment=*/subsystem=datasources/data-source=*

    /subsystem=datasources/data-source=*

    /subsystem=datasources/data-source=ExampleDS

    /deployment=*/subsystem=datasources/data-source=*
Classification: jdbc-driver
  • 默认值:false
    Expand
    PATH 属性 操作

    /subsystem=datasources/jdbc-driver=*
类别:xa-data-source
  • 默认值:false
    Expand
    PATH 属性 操作

    /subsystem=datasources/xa-data-source=*

    /deployment=*/subsystem=datasources/xa-data-source=*

    /deployment=*/subdeployment=*/subsystem=datasources/xa-data-source=*

类型:logging

类别:logger
  • 默认值:false
    Expand
    PATH 属性 操作

    /subsystem=logging/logger=*

    /subsystem=logging/logging-profile=*/logger=*
类别:logging-profile
  • 默认值:false
    Expand
    PATH 属性 操作

    /subsystem=logging/logging-profile=*

类型:mail

类别:mail-session
  • 默认值:false
    Expand
    PATH 属性 操作

    /subsystem=mail/mail-session=*

类型:naming

类别:binding
  • 默认值:false
    Expand
    PATH 属性 操作

    /subsystem=naming/binding=*

类型:resource-adapters

类别:resource-adapters
  • 默认值:false
    Expand
    PATH 属性 操作

    /subsystem=resource-adapters/resource-adapter=*

类型:security

类别:security-domain
  • 默认值:false
    Expand
    PATH 属性 操作

    /subsystem=security/security-domain=*
10.8.11.2.  安全约束引用

类型:core

类别:access-control
  • requires-addressable: true
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /core-service=management/access=authorization

    /subsystem=jmx

    non-core-mbean-sensitivity
类别:credential
  • requires-addressable: false
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=mail/mail-session=*/server=pop3

    username , password

    /subsystem=mail/mail-session=*/server=imap

    username, password

    /subsystem=datasources/xa-data-source=*

    user-name, recovery-username, password, recovery-password

    /subsystem=mail/mail-session=*/custom=*

    username, password

    /subsystem=datasources/data-source=*"

    user-name, password

    /subsystem=remoting/remote-outbound-connection=*"

    username

    /subsystem=mail/mail-session=*/server=smtp

    username , password

    /subsystem=web/connector=*/configuration=ssl

    key-alias, password

    /subsystem=resource-adapters/resource-adapter=*/connection-definitions=*"

    recovery-username, recovery-password
类别:domain-controller
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作
类别:domain-names
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作
类别:extensions
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /extension=*
类别:jvm
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /core-service=platform-mbean/type=runtime

    input-arguments, boot-class-path, class-path, boot-class-path-supported, library-path
类别:management-interfaces
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /core-service=management/management-interface=native-interface

    /core-service=management/management-interface=http-interface
类别:module-loading
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /core-service=module-loading
类别:patching
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /core-service=patching/addon=*

    /core-service=patching/layer=*"

    /core-service=patching
类别:read-whole-config
  • requires-addressable: false
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /

    read-config-as-xml
类别:security-domain
  • requires-addressable: true
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=security/security-domain=*
类别:security-domain-ref
  • requires-addressable: true
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=datasources/xa-data-source=*

    security-domain

    /subsystem=datasources/data-source=*

    security-domain

    /subsystem=ejb3

    default-security-domain

    /subsystem=resource-adapters/resource-adapter=*/connection-definitions=*

    security-domain, recovery-security-domain, security-application, security-domain-and-application
类别:security-realm
  • requires-addressable: true
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /core-service=management/security-realm=*
类别:security-realm-ref
  • requires-addressable: true
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=remoting/connector=*

    security-realm

    /core-service=management/management-interface=native-interface

    security-realm

    /core-service=management/management-interface=http-interface

    security-realm

    /subsystem=remoting/remote-outbound-connection=*

    security-realm
类别:security-vault
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /core-service=vault
类别:service-container
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /core-service=service-container
类别:snapshots
  • requires-addressable: false
  • requires-read: false
  • requires-write: false
    Expand
    PATH 属性 操作

    /

    take-snapshot, list-snapshots, delete-snapshot
类别:socket-binding-ref
  • requires-addressable: false
  • requires-read: false
  • requires-write: false
    Expand
    PATH 属性 操作

    /subsystem=mail/mail-session=*/server=pop3

    outbound-socket-binding-ref

    /subsystem=mail/mail-session=*/server=imap

    outbound-socket-binding-ref

    /subsystem=remoting/connector=*

    socket-binding

    /subsystem=web/connector=*

    socket-binding

    /subsystem=remoting/local-outbound-connection=*

    outbound-socket-binding-ref

    /socket-binding-group=*/local-destination-outbound-socket-binding=*

    socket-binding-ref

    /subsystem=remoting/remote-outbound-connection=*

    outbound-socket-binding-ref

    /subsystem=mail/mail-session=*/server=smtp

    outbound-socket-binding-ref

    /subsystem=transactions

    process-id-socket-binding, status-socket-binding, socket-binding
类别:socket-config
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /interface=*

    resolve-internet-address

    /core-service=management/management-interface=native-interface

    port, interface, socket-binding

    /socket-binding-group=*

    /core-service=management/management-interface=http-interface

    port, secure-port, interface, secure-socket-binding, socket-binding

    /

    resolve-internet-address

    /subsystem=transactions

    process-id-socket-max-ports
类别:system-property
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /core-service=platform-mbean/type=runtime

    system-properties

    /system-property=*

    /

    resolve-expression

类型:datasources

类别:data-source-security
  • requires-addressable: false
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=datasources/xa-data-source=*

    user-name, security-domain, password

    /subsystem=datasources/data-source=*

    user-name, security-domain, password

类型:jdr

类别:jdr
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=jdr

    generate-jdr-report

类型:jmx

类别:jmx
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=jmx

类型:mail

类别:mail-server-security
  • requires-addressable: false
  • requires-read: false
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=mail/mail-session=*/server=pop3

    username, tls, ssl, password

    /subsystem=mail/mail-session=*/server=imap

    username, tls, ssl, password

    /subsystem=mail/mail-session=*/custom=*

    username, tls, ssl, password

    /subsystem=mail/mail-session=*/server=smtp

    username, tls, ssl, password

类型:naming

类别:jndi-view
  • requires-addressable: false
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=naming

    jndi-view
类别:naming-binding
  • requires-addressable: false
  • requires-read: false
  • requires-write: false
    Expand
    PATH 属性 操作

    /subsystem=naming/binding=*

类型:remoting

类别:remoting-security
  • requires-addressable: false
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=remoting/connector=*

    authentication-provider, security-realm

    /subsystem=remoting/remote-outbound-connection=*

    username, security-realm

    /subsystem=remoting/connector=*/security=sasl

类型:resource-adapters

Classification: resource-adapter-security
  • requires-addressable: false
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=resource-adapters/resource-adapter=*/connection-definitions=*

    security-domain, recovery-username, recovery-security-domain, security-application, security-domain-and-application, recovery-password

类型:security

类别:misc-security
  • requires-addressable: false
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=security

    deep-copy-subject-mode

类型:web

类别:web-access-log
  • requires-addressable: false
  • requires-read: false
  • requires-write: false
    Expand
    PATH 属性 操作

    /subsystem=web/virtual-server=*/configuration=access-log
类别:web-connector
  • requires-addressable: false
  • requires-read: false
  • requires-write: false
    Expand
    PATH 属性 操作

    /subsystem=web/connector=*
类别:web-ssl
  • requires-addressable: false
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=web/connector=*/configuration=ssl
类别:web-sso
  • requires-addressable: false
  • requires-read: true
  • requires-write: true
    Expand
    PATH 属性 操作

    /subsystem=web/virtual-server=*/configuration=sso
类别:web-valve
  • requires-addressable: false
  • requires-read: false
  • requires-write: false
    Expand
    PATH 属性 操作

    /subsystem=web/valve=*

10.9. 网络安全性

10.9.1. 保护管理接口

总结

在测试环境里,我们通常在由管理控制台、管理 CLI 和其他 API 实现组成的管理接口上不设置安全层来运行 JBoss EAP 6 。这可以允许快速的开发和配置修改。

此外,silent 验证模式也是默认的,这允许主机上的本地客户可以连接管理 CLI 而无需用户名和密码。这对于本地用户和管理 CLI 脚本是很方便的,但它可以根据需要禁用。其步骤请参考 第 10.7.6 节 “从默认的安全区删除无提示验证”
当你开始测试并准备移至产品环境时,至少通过下列方式保护管理接口是极其重要的:

10.9.2. 指定 JBoss EAP 6 使用的网络接口

概述

隔离服务以使它们只被需要它们的客户访问,这样可以增强网络的安全性。JBoss EAP 在其默认配置里包含两个接口,两者都绑定到 IP 地址127.0.0.1localhost。其中一个被称为 management,它被管理控制台、CLI 和 API 使用。另外一个被称为 public,被用来部署应用程序。这些接口并不特殊或有什么含义,只是作为起点来提供。

management 接口默认使用端口 9990 和 9999,而public 接口使用端口 8080 或 8443(如果使用 HTTPS)。
你修改管理接口或公共接口的 IP 地址,或者两者都修改。

警告

如果你将管理接口开放给远程主机可以访问的其他网络接口,请注意潜在的安全问题。多数情况下,我们不建议为管理接口提供远程访问。
  1. 停止 JBoss EAP 6 服务器。

    以合适的方式对操作系统发送中断信号来停止 JBoss EAP 6。如果你以前台应用程序的方式运行 JBoss EAP 6,那通常的做法是按 Ctrl+C 键。
  2. 重启 JBoss EAP 6,指定绑定地址。

    使用 -b 命令行选项在特定接口上启动 JBoss EAP 6。

    例 10.27. 指定公共接口。

    EAP_HOME/bin/domain.sh -b 10.1.1.1

    例 10.28. 指定管理接口。

    EAP_HOME/bin/domain.sh -bmanagement=10.1.1.1

    例 10.29. 为每个接口指定不同的地址。

    EAP_HOME/bin/domain.sh -bmanagement=127.0.0.1 -b 10.1.1.1

    例 10.30. 绑定公共接口到所有的网络接口上。

    EAP_HOME/bin/domain.sh -b 0.0.0.0
你也可以直接编辑你的 XML 配置文件以修改默认的绑定地址。然而,如果你这么做,你将不能使用 -b 命令行选项在运行时指定 IP 地址,所以我们不推荐这么做。如果确实要这么做,请在编辑 XML 文件前完全停止 JBoss EAP 6。

10.9.3. JBoss EAP 6 使用的网络端口

JBoss EAP 6 的默认配置使用的端口取决于下列因素:
  • 你的服务器组是否使用了默认的套接字绑定组,或者自定义的套接字绑定组。
  • 单独部署的要求。

注意

你可以配置一个数字的端口偏移量,以减缓当在同一个服务服务器上运行多个服务器时端口冲突。如果你的服务器使用了数字的端口偏移量,在它的服务器组的套接字绑定组的默认端口上添加偏移量。例如,如果套接字绑定组的 HTTP 端口是 8080,而你的服务器使用了端口偏移量为 100,那么它的 HTTP 端口是 8180。
除非额外指定,这个端口将使用 TCP 协议。

默认的套接字绑定组

  • full-ha-sockets
  • full-sockets
  • ha-sockets
  • standard-sockets
Expand
表 10.5. 默认的套接字绑定组的引用
名称 端口 多点传送端口 描述 full-ha-sockets full-sockets ha-socket standard-socket
ajp 8009 Apache JServ 协议,用于 HTTP 群集和负载平衡。
http 8080 用于已部署应用程序的默认端口。
https 8443 已部署的应用程序和客户间的用 SSL 加密的连接。
jacorb 3528 用于 JTS 事务的 CORBA 服务和其他依赖于 ORB 的服务。
jacorb-ssl 3529 SSL 加密的 CORBA 服务。
jgroups-diagnostics 7500 多点传送。用于 HA 群集里的 Peer 发现。不能使用管理界面进行配置。
jgroups-mping 45700 多点传送。用于在 HA 群集里发现初始成员资格。
jgroups-tcp 7600 HA 群集里使用 TCP 的多点传送 Peer 发现。
jgroups-tcp-fd 57600 用于 TCP 上的 HA 失败检测。
jgroups-udp 55200 45688 HA 群集里使用 UDP 的多点传送 Peer 发现。
jgroups-udp-fd 54200 用于 UDP 上的 HA 失败检测。
messaging 5445 JMS 服务。
messaging-group 被 HornetQ JMS 广播和发现组引用。
messaging-throughput 5455 JMS remoting 所使用的。
mod_cluster 23364 用于 JBoss EAP 6 和 HTTP 加载平衡器之间通讯的多点传送端口。
osgi-http 8090 由使用 OSGi 子系统的内部组件使用。不能通过管理界面进行配置。
remoting 4447 用于远程 EJB 调用。
txn-recovery-environment 4712 JTA 事务恢复管理者。
txn-status-manager 4713 JTA / JTS 事务管理者。
管理端口

除了套接字绑定组,每个主机控制台都打开另外两个端口用于管理:

  • 9990 - Web 管理控制台的端口
  • 9999 - 管理控制台和 API 使用的端口
总结

多数产品环境都使用防火墙作为总体网络安全策略的一部分。如果你需要多个 EAP 服务器来与其他 EAP 服务器或外部服务(如 Web 服务器或数据库)来通讯,你的防火墙必须考虑这一点。管理良好的防火墙只会打开操作所需的端口,它会限制对某些 IP 地址、子网和网络协议的端口的访问。

不过,关于防火墙的完整讨论超出了本文档的范畴。

前提条件

  • 确定你要打开的端口。
  • 对防火墙软件的理解是必需的。在红帽企业版 Linux 6 里,这个过程会使用 system-config-firewall 命令。微软的 Windows 服务器包括了内置的防火墙,以及几个可用于任何平台的第三方的防火墙解决方案。
假设

这个过程配置防火墙是基于如下假设的:

  • 操作系统为红帽企业版 Linux 6。
  • JBoss EAP 6 运行在主机 10.1.1.2上。或者,EAP 服务器具有自己的防火墙。
  • 网络防火墙服务器运行在主机 10.1.1.1 的接口 eth0 上,且具有外部的接口 eth1
  • 你想把端口 5445(JMS 使用的端口)上的流量转发到 JBoss EAP 6。网络防火墙应该不允许其他流量通过。

过程 10.33. 管理和 JBoss EAP 6 一起使用的网络防火墙

  1. 登录到管理控制台。

    登录到管理控制台。在默认情况下,它运行在 http://localhost:9990/console/ 上。
  2. 确定套接字绑定组使用的套接字绑定。

    点击管理控制台右上方的 Profiles 标签。在屏幕的左侧会显示一系列菜单。菜单底部是 General Configuration。点击它下面的 Socket BindingSocket Binding Declarations 屏幕将会出现,一开始它会显示 standard-sockets 组。你可以从右侧的复合框里来选择不同的组。

    注意

    如果你使用的是独立服务器,它只有一个套接字绑定组。
    套接字名称和端口将会出现,每页有 8 个值。你可以使用表下面的箭头来进行浏览。
  3. 确定你要打开的端口。

    根据特定端口的功能以及系统环境的要求,你可能需要在防火墙上打开某些端口。
  4. 配置防火墙将通讯转发到 JBoss EAP 6。

    执行这些步骤来配置网络防火墙以允许指定端口上的通讯。
    1. 登录到防火墙主机并以根用户身份打开命令行提示。
    2. 执行 system-config-firewall 来启动防火墙配置工具。GUI 或命令行工具根据你登录到防火墙系统的方式启动。这个任务假设你通过 SSH 登录并使用了命令行接口。
    3. 使用 TAB 键切换到 Customize 按钮,然后按 ENTER 键。Trusted Services 屏幕将会出现。
    4. 不要修改任何值,使用 TAB 键切换到 Forward 按钮,然后按 ENTER 键进入下一屏幕。Other Ports 屏幕将出现。
    5. 使用 TAB 键切换到 <Add> 按钮,然后按 ENTER 键。Port and Protocol 屏幕将会出现。
    6. Port / Port Range 字段里输入5445 ,然后使用 TAB 键切换到 Protocol 字段,并输入 tcp。使用 TAB 键切换到 OK 按钮,然后按 ENTER 键。
    7. 使用 TAB 键切换到 Forward 按钮,直至你到达 Port Forwarding 屏幕。
    8. 使用 TAB 键切换到 <Add> 按钮,然后按 ENTER 键。
    9. 填写下列值以设立端口映射到 5445。
      • 源接口:eth1
      • 协议:tcp
      • 端口 / 端口范围:5445
      • 目的 IP 地址:10.1.1.2
      • 端口 / 端口范围:5445
      使用 TAB 键切换到 OK 按钮,然后按 ENTER
    10. 使用 TAB 键切换到 Close 按钮,然后按 ENTER
    11. 使用 TAB 键切换到 OK 按钮,然后按 ENTER。要应用这些改动,阅读警告提示并点击 Yes
  5. 在你的 JBoss EAP 6 主机上配置防火墙。

    一些机构选择在 JBoss EAP 6 服务器上配置防火墙,并关闭非操作必需的端口。请参考 第 10.9.3 节 “JBoss EAP 6 使用的网络端口” 并确定要打开的端口,然后关闭其他端口。红帽企业版 6 的默认配置关闭所有的端口,除了 22(用于 SSH)和 5353(用于多点传送 DNS)。当你在配置端口的时候,请确保你可以从物理上访问服务器,这样就不会不经意地将自己关在外面。
结果

配置了防火墙,它会按照你在防火墙配置里指定的将通讯转发到内部的 JBoss EAP 6 服务器。如果你选择在服务器上启用防火墙,除了需要运行应用程序的端口,所有的端口将被关闭。

10.10. Java 安全性管理者

10.10.1. 关于 Java 安全性管理者

Java 安全性管理者(Java Security Manager)
Java 安全性管理者是一个管理 Java 虚拟机(JVM)sandbox 外部边界的类,它控制代码在 JVM 里执行时如何和外部的资源交互。当 Java 安全性管理者被激活时,Java API 在执行许多有潜在风险的操作之前会检查 Java 安全性管理者以获得批准。
Java 安全性管理者使用一个安全策略来确定是否允许或拒绝给定的动作。

10.10.2. 在 Java 安全管理者里运行 JBoss EAP 6

要指定一个 Java 安全管理者策略,你需要编辑在引导过程中传递给域或服务器实例的 Java 选项。出于这个原因,你不能将参数作为选项传递给 domain.shstandalone.sh 脚本。下面的过程会指引你配置实例以在 Java 安全管理者里运行 JBoss EAP。

先决条件

  • 在执行下列过程之前,你需要用 JDK 里包含的 policytool 编写一个安全策略。这个过程假定你的策略位于 EAP_HOME/bin/server.policy。您也可以用任何文本编辑器手工编写安全策略并将其保存为 EAP_HOME/bin/server.policy
  • 在编辑配置文件之前,域或独立服务器必须完全停止。
如果你有域成员跨越多个系统,请对每个域里的物理主机或实例执行下列过程。

过程 10.34. 为 JBoss EAP 6 配置安全管理者

  1. 打开配置文件。

    打开配置文件进行编辑。根据你使用的是域还是独立服务器,这个文件位于两个位置中的一个。它不是用来启动服务器或域的可执行文件。
    • 受管域

      EAP_HOME/bin/domain.conf
    • 独立服务器

      EAP_HOME/bin/standalone.conf
  2. 在文件里添加 Java 选项。

    为了确保使用 Java 选项,请在代码块里添加以下列行开始的内容:
    if [ "x$JAVA_OPTS" = "x" ]; then
    
    你可以修改 -Djava.security.policy 值来制定安全策略的准确位置。这个值应该只有一行,且不能中断。你也可以修改 -Djava.security.debug、指定调试级别来记录更多或更少的信息。完整的选项是 accesspolicyaccess:failurefailure,access,policy
    JAVA_OPTS="$JAVA_OPTS -Djava.security.manager -Djboss.home.dir=$PWD/.. -Djava.security.policy==$PWD/server.policy -Djava.security.debug=access:failure"
  3. 启动域或服务器。

    正常地启动域或服务器。

10.10.3. 关于 Java 安全管理者策略

安全策略
以不同代码类别表示的一系列权限。Java 安全管理者将应用程序的动作请求和安全策略进行比较。如果某个动作是策略所允许的,那么安全管理者将允许这个动作执行。如果这个动作是策略所不允许的,那么将拒绝这个动作的执行。安全策略可以根据代码的位置或签名来定义权限。
Java 安全管理者和所用的安全策略是用虚拟机选项 java.security.managerjava.security.policy 配置的。

10.10.4. 编写 Java 安全性管理者策略

简介

多数 JDK 和 JRE 版本里都包含一个 policytool 程序,它用于创建和编辑 Java 安全管理者安全策略。关于 policytool 的详细信息请访问 http://docs.oracle.com/javase/6/docs/technotes/tools/

基本信息

安全策略由下列配置元素组成:

CodeBase
产生代码的 URL 位置(不包括主机和域信息)。这个参数是可选的。
SignedBy
密钥库里用来引用签名者(其私有密钥用于为代码签名)的别名。这可以是单个的值,也可以是用逗号隔开的值的列表。如果忽略它,签名的缺席与否都不会影响 Java 安全管理者。
Principals
principal_type/principal_name 对的列表,它必须出现在执行线程的 principal 集里。Principal 条目是可选的。如果忽略它,则表示 “任何 principals“。
Permissions
赋予代码的权限。许多权限是作为 Java EE 规格的一部分提供的。本文档只涵盖由 JBoss EAP 6 提供的其他权限。

过程 10.35. 设置新的 Java 安全性管理者策略

  1. 启动 policytool.

    以下列方式之一启动 policytool 工具。
    • 红帽企业版 Linux

      在 GUI 或命令行提示下,运行 /usr/bin/policytool
    • Microsoft Windows Server

      从开始菜单或 Java 安装的 bin\ 里运行 policytool.exe。在不同系统里,其位置可能会不一样。
  2. 创建一个策略。

    要创建一个策略,请选择 Add Policy Entry。添加你需要的参数,然后点击 Done
  3. 编辑现有的策略

    从现有的策略列表里选择策略,并选择 Edit Policy Entry 按钮。然后根据需要编辑相关参数。
  4. 删除现有的策略。

    从现有的策略列表里选择策略,并选择 Remove Policy Entry 按钮。

JBoss EAP 6 专有的权限

org.jboss.security.SecurityAssociation.getPrincipalInfo
提供对 org.jboss.security.SecurityAssociationgetPrincipal()getCredential() 方法的访问。使用这个运行时权限涉及的风险是可以查看当前的线程调用者和凭证。
org.jboss.security.SecurityAssociation.getSubject
提供对 org.jboss.security.SecurityAssociationgetSubject() 方法的访问。
org.jboss.security.SecurityAssociation.setPrincipalInfo
提供对 org.jboss.security.SecurityAssociationsetPrincipal()setCredential()setSubject()pushSubjectContext()popSubjectContext() 方法的访问。使用这个运行时权限涉及的风险是可以设置当前的线程调用者和凭证。
org.jboss.security.SecurityAssociation.setServer
提供对 org.jboss.security.SecurityAssociationsetServer 方法的访问。使用这个运行时权限涉及的风险是可以启用或禁用调用者 principal 和凭证的多线程存储。
org.jboss.security.SecurityAssociation.setRunAsRole
提供对 org.jboss.security.SecurityAssociationpushRunAsRolepopRunAsRolepushRunAsIdentitypopRunAsIdentity 方法的访问。使用这个运行时权限涉及的风险是可以修改当前调用者的 run-as 角色 principal。
org.jboss.security.SecurityAssociation.accessContextInfo
提供对 org.jboss.security.SecurityAssociationaccessContextInfoaccessContextInfo 的 getter 和 setter 方法的访问。这允许你设置和获取当前安全上下文信息。
org.jboss.naming.JndiPermission
提供对指定 JNDI 树路径里的文件和目录或递归至全部文件和子目录的特殊权限。JndiPermission 由一个路径名和相对于文件或目录的一系列有效权限组成。
可用的权限包括:
  • bind
  • rebind
  • unbind
  • lookup
  • list
  • listBindings
  • createSubcontext
  • all
Pathnames ending in /* indicate that the specified permissions apply to all files and directories of the pathname. Pathnames ending in /- indicate recursive permissions to all files and subdirectories of the pathname. Pathnames consisting of the special token <<ALL BINDINGS>> matches any file in any directory.
org.jboss.security.srp.SRPPermission
保护对敏感 SRP 信息(如私有会话密钥和私有密钥)访问的自定义权限类。这个权限没有定义任何动作。getSessionKey() 目标提供对 SRP 协商导致的私有会话密钥的访问。对这个密钥的访问允许你加密和解密已经用这个会话密钥加密的消息。
org.hibernate.secure.HibernatePermission
这个权限类提供对于安全 Hibernate 会话的基本权限。这个属性的目标是实体名称。可用的动作包括:
  • insert
  • delete
  • update
  • read
  • * (all)
org.jboss.metadata.spi.stack.MetaDataStackPermission
提供一个自定义权限类来控制调用者如何和元数据栈进行交互。可用的权限是:
  • modify
  • push (onto the stack)
  • pop (off the stack)
  • peek (onto the stack)
  • * (all)
org.jboss.config.spi.ConfigurationPermission
配置属性的安全设置。只定义权限目标名称,不定义动作。这个属性的目标包括:
  • <property name> (the property this code has permission to set)
  • * (all properties)
org.jboss.kernel.KernelPermission
对于内核配置的安全访问。只定义权限目标,不定义动作。这个属性的目标包括:
  • access (to the kernel configuration)
  • configure (implies access)
  • * (all)
org.jboss.kernel.plugins.util.KernelLocatorPermission
对于内核的安全访问。只定义权限目标,不定义动作。这个属性的目标包括:
  • kernel
  • * (all)

10.10.5. 调试安全管理者策略

你可以启用调试信息来帮助你解决和安全策略相关的问题。java.security.debug 选项配置和安全相关的信息的级别。java -Djava.security.debug=help 命令将产生具有完整调试选项的帮助信息。当解决和安全相关的故障而完全不知道原因时,设置调试级别为 all 是很有用的。但对于普通的用途而言,这会产生过多的信息。一般默认的选项是 access:failure

过程 10.36. 启用普通调试

  • 这个过程将启用普通级别的和安全相关的调试信息。

    在服务器配置文件里添加下列行。
    • 如果 JBoss EAP 6 实例运行在受管域里,这一行将添加到 bin/domain.conf()或 bin/domain.conf.bat(Windows)。
    • 如果 JBoss EAP 6 实例作为独立服务器运行,这一行将添加到 bin/standalone.conf()或 bin\standalone.conf.bat(Windows)。
Linux
JAVA_OPTS="$JAVA_OPTS -Djava.security.debug=access:failure"
Windows
JAVA_OPTS="%JAVA_OPTS% -Djava.security.debug=access:failure"
结果

启用了普通级别的和安全相关的调试信息。

10.11. 应用程序的安全性

10.11.1. 启用/禁用基于描述符的属性替换

介绍

jboss-as-ee_1_1.xsd 引入了对描述符属性替换的有限控制。本节内容涵盖了配置基于描述符的属性替换所需的步骤。

基于描述符的属性替换标记具有的布尔值:
  • 如果设置为 true,属性替换将被启用。
  • 如果设置为 false,属性替换将被禁用。

过程 10.37. jboss-descriptor-property-replacement

jboss-descriptor-property-replacement 用于在下列描述符里启用或禁用属性替换:
  • jboss-ejb3.xml
  • jboss-app.xml
  • jboss-web.xml
  • *-jms.xml
  • *-ds.xml
jboss-descriptor-property-replacement 的默认值是 true
  1. 在管理 CLI 里,运行下列命令来确定 jboss-descriptor-property-replacement 的值:
    /subsystem=ee:read-attribute(name="jboss-descriptor-property-replacement")
  2. 运行下列命令来配置其行为:
    /subsystem=ee:write-attribute(name="jboss-descriptor-property-replacement",value=VALUE)

过程 10.38. spec-descriptor-property-replacement

spec-descriptor-property-replacement 用于在下列描述符里启用或禁用属性替换:
  • ejb-jar.xml
  • persistence.xml
spec-descriptor-property-replacement 的默认值是 false
  1. 在管理 CLI 里,运行下列命令来确认 spec-descriptor-property-replacement 的值:
    /subsystem=ee:read-attribute(name="spec-descriptor-property-replacement")
  2. 运行下列命令来配置其行为:
    /subsystem=ee:write-attribute(name="spec-descriptor-property-replacement",value=VALUE)
结果

成功地配置了基于描述符的属性替换标记。

10.12. SSL 加密

10.12.1. 对 JBoss EAP 6 Web 服务器实施 SSL 加密

简介

许多 web 应用程序都要求对客户端和服务器间的连接进行 SSL 加密,这也被称为 HTTPS 连接。你可以通过这个过程对服务器或服务器组启用 HTTPS

前提条件

  • 你需要一系列 SLL 加密密钥和加密证书。你可以从证书签名机构购买或者使用命令行工具来生成。关于使用红帽企业版 Linux 工具来生成加密密钥,请参考 第 10.12.2 节 “生成 SSL 密钥和证书”
  • 你需要知道你的环境和设置的下列细节:
    • 你的证书文件的完整目录名和路径
    • 你的加密密钥的密码。
  • 你需要运行管理 CLI 并连接到域控制器或独立服务器。

注意

这个过程使用适合用于受管域的 JBoss EAP 6 配置的命令。如果你使用的是独立服务器,请从任何管理 CLI 命令的开头将 /profile=default 删除。

过程 10.39. 配置 JBoss Web 服务器以使用 HTTPS

  1. 添加新的 HTTPS 连接器。

    执行下列管理 CLI 命令来修改配置。这会创建一个新的加密连接器,名为 HTTPS。它使用 https 模式、https 套接字绑定(默认为 8443 端口),且被设置为安全的。

    例 10.31. 管理 CLI 命令

    /profile=default/subsystem=web/connector=HTTPS/:add(socket-binding=https,scheme=https,protocol=HTTP/1.1,secure=true)
    
  2. 配置 SSL 加密证书和密钥。

    执行下列 CLI 命令来配置你的 SSL 证书,请用自己的值来替换例子里的值。这个例子假设密钥库被复制到服务器的配置目录,对于受管域来说,也就是EAP_HOME/domain/configuration/

    例 10.32. 管理 CLI 命令

    /profile=default/subsystem=web/connector=HTTPS/ssl=configuration:add(name=https,certificate-key-file="${jboss.server.config.dir}/keystore.jks",password=SECRET, key-alias=KEY_ALIAS)
    
    关于连接器的 SSL 属性参数的完整列表,请参考 第 10.12.3 节 “SSL 连接器引用”
  3. 部署应用程序。

    部署一个使用你已经配置好的配置集的应用程序到服务器组。如果你使用的是独立服务器,将这个应用程序部署至服务器。它的 HTTP 请求将使用新的 SSL 加密的连接。

10.12.2. 生成 SSL 密钥和证书

要使用 SSL 加密的 HTTP 协议(HTTPS)以及其他类型的通讯,你需要一个签名的加密证书。你可以从证书认证机构(CA)购买或者使用自签名(self-signed)的证书。许多第三方机构认为自签名的证书是不可靠的,但它适合于内部的测试目的。
这个过程让你使用红帽企业版 Linux 里的工具创建自签名的证书。

前提条件

  • 你需要 keytool 工具,任何 JDK 都提供它。红帽企业版 Linux 上的 OpenJDK 将这个命令安装在 /usr/bin/keytool
  • 请理解 keytool 命令的语法和参数。这个过程将使用非常浅显的说明,因为对 SSL 证书或 keytool 命令的深入讨论都超出了本文档的范畴。

过程 10.40. 生成 SSL 密钥和证书

  1. 用公共和私有密钥生成密钥库。

    运行下列命令来当前目录里生成带有别名 jboss 的名为server.keystore 的密钥库。
    keytool -genkeypair -alias jboss -keyalg RSA -keystore server.keystore -storepass mykeystorepass --dname "CN=jsmith,OU=Engineering,O=mycompany.com,L=Raleigh,S=NC,C=US"
    下表描述了用于 keytool 命令的参数:
    Expand
    参数 描述
    -genkeypair keytool 命令生成包含公共和私有密钥的密钥对。
    -alias 密钥库的别名。这个值是任意的,但别名 jboss 是 JBoss Web 服务器使用的默认值。
    -keyalg 密钥对的生成算法。这个例子里是 RSA
    -keystore 密钥库文件的名称和位置。默认的位置是当前的目录。你可以选择任意名字。在这个例子里是 server.keystore
    -storepass 这个密码用于针对密钥库进行验证,从而读取密钥。这个密码长度必须至少为 6 且在访问时密钥库时提供。在这个例子里,我们使用 mykeystorepass。如果你忽略这个参数,在执行命令时你将被提示输入它。
    -keypass
    这是实际密钥的密码。

    注意

    由于实现的限制,它必须和库的密码相同。
    --dname 引号括起的描述密钥的可区分名称的字符串,如"CN=jsmith,OU=Engineering,O=mycompany.com,L=Raleigh,C=US"。这个字符串是下列组件的组合:
    • CN - 常用名或主机名。如果主机名是 "jsmith.mycompany.com",那么 CN 就是 "jsmith"。
    • OU - 机构单元,如 "Engineering"。
    • O - 机构名称,如 "mycompany.com"。
    • L - 地区,如 "Raleigh" 或 "London"。
    • S - 州或省,如 "NC"。这个参数是可选的。
    • C - 两个字符的国家代码,如 "US" 或 "UK"。
    当你执行上述命令时,你会被提示输入下列信息:
    • 如果你在命令行没有使用 -storepass 参数,你会被要求输入密钥库的密码。在下一次提示时再次输入新密码。
    • 如果你在命令行没有使用 -keypass 参数,你会被要求输入密钥密码。按 Enter 将其设置为和密钥密码相同的值。
    当命令执行完毕时,server.keystore 文件包含了带有别名 jboss 的单个密钥。
  2. 检验这个密钥。

    通过下列命令检验这个密钥是否正常工作。
    keytool -list -keystore server.keystore
    你会被提示输入密钥库密码。密钥库的内容将被显示(这个例子里是名为 jboss 的单个密钥)。请注意 jboss 密钥的类型是 keyEntry。这表示密钥库包含这个密钥的公共和私有条目。
  3. 生成一个证书签名请求。

    运行下列命令使用步骤一里创建的密钥库里的公共密钥来生成一个证书签名请求。
    keytool -certreq -keyalg RSA -alias jboss -keystore server.keystore -file certreq.csr
    系统会提示你输入密码以针对密钥库进行验证。然后 keytool 命令将在当前工作目录里创建一个名为 certreq.csr 的证书签名请求。
  4. 测试新生成的证书签名请求。

    通过下列命令测试证书的内容。
    openssl req -in certreq.csr -noout -text
    证书细节将被显示。
  5. 可选:提交证书签名请求到证书认证机构(CA)。

    证书机构(Certificate Authority,CA)可以验证你的证书,它被第三方的客户认为是可靠的。CA 向你提供一个签名的证书,还有一个或多个可选的中间证书。
  6. 可选:从密钥库导出自签名的证书

    如果你只需要用来进行测试或内部使用,你可以使用自签名的证书。你可以从密钥库导出在步骤一创建的证书:
    keytool -export -alias jboss -keystore server.keystore -file server.crt
    系统会提示你输入密码以针对密钥库进行验证。名为 server.crt 的自签名的证书将在当前工作目录里创建。
  7. 导入已签名的证书以及任何中间的证书。

    按照 CA 里说明的顺序导入每个证书。对于每个要导入的证书,请用实际的文件名替换 intermediate.caserver.crt。如果你的证书未作为独立的文件提供,请为每个证书创建一个独立的文件,并将其内容粘贴到文件里。

    注意

    你的已签名的证书和密钥都是有价值的资产。请小心地在服务器间传递。
    keytool -import -keystore server.keystore -alias intermediateCA -file intermediate.ca
    keytool -import -alias jboss -keystore server.keystore -file server.crt
  8. 测试你的证书是否已经成功导入。

    运行下列命令,遇提示时输入密钥库密码。密钥库的内容将被显示,证书将是列表里的一部分。
    keytool -list -keystore server.keystore
结果

你签名的证书现在已包含在密钥库里了,它可用来加密 SSL 连接,包括 HTTPS web 服务器通讯。

10.12.3. SSL 连接器引用

JBoss Web 连接器可能包括了下列 SSL 配置属性。提供的 CLI 命令是针对使用 default 配置集的受管域的。按照你的需要修改这个配置集名称(对于受管域),或者忽略命令行的 /profile=default 部分(对于独立服务器)。
Expand
表 10.6. SSL 连接器属性
属性 描述 CLI 命令
名称
SSL 连接器的显示名称。
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=name,value=https)
verify-client
设置为 true 表示在接受连接前需要客户的有效证书链。如果你希望 SSL 栈来请求客户证书,可以将其设为 want。设置为 false(默认值)表示不要求证书链,除非客户请求被使用 CLIENT-CERT 验证的安全约束保护的资源。
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=verify-client,value=want)
verify-depth
中间证书发行者在决定客户是否具有有效证书前检查的最多次数。默认值是 10
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=verify-depth,value=10)
certificate-key-file
保存服务器证书的密钥库文件的完整文件路径和名称。对于 JSSE 加密,这个证书文件将是唯一的,而 OpenSSL 则使用几个文件。默认值是运行 JBoss EAP 6 的用户的主目录下的 .keystore。如果你的 keystoreType 没有使用文件,请将这个参数设置为空字符串。
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=certificate-key-file,value=../domain/configuration/server.keystore)
certificate-file
如果你使用 OpenSSL 加密,请设置这个参数的值为包含服务器证书的文件的路径。
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=certificate-file,value=server.crt)
password
用于信任库和密钥库的密码。在下面的例子里,请用自己的密码替换 PASSWORD
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=password,value=PASSWORD)
protocol
要使用的 SSL 协议的版本。支持的值包括 SSLv2SSLv3TLSv1SSLv2+SSLv3ALL。默认的是 ALL
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=protocol,value=ALL)
cipher-suite
用逗号隔开的所允许的加密密码的列表。JSSE 的默认 JVM 包含不应该使用的弱密码。这个例子只列出了两个可能的密码,但实际的例子可能使用更多。
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=cipher-suite, value="TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA")
key-alias
用于密钥库里的服务器证书的别名。在下面的例子里,请用你的证书别名替换 KEY_ALIAS
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=key-alias,value=KEY_ALIAS)
truststore-type
信任库的类型。不同的密钥库包括 PKCS12 和 Java 的标准 JKS
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=truststore-type,value=jks)
keystore-type
密钥库的类型那个。不同的密钥库类型包括 PKCS12 和 Java 的标准 JKS
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=keystore-type,value=jks)
ca-certificate-file
包含 CA 证书的文件。对于 JSSE 是 truststoreFile,并对密钥库使用相同密码。ca-certificate-file 文件被用来检验客户证书。
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=certificate-file,value=ca.crt)
ca-certificate-password
用于 ca-certificate-file 的证书密码。在下面的例子里,请用自己的掩码密码替换其中的 MASKED_PASSWORD
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=ca-certificate-password,value=MASKED_PASSWORD)
ca-revocation-url
包含撤销列表的文件或 URL。它指向 crlFile(JSSE )或 SSLCARevocationFile(SSL)。
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=ca-revocation-url,value=ca.crl)
session-cache-size
SSL 会话缓存的大小。这个属性仅用于 JSSE 连接器。默认值是 0,它表示缓存大小是无限的。
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=session-cache-size,value=100)
session-timeout
在缓存的 SSLSession 过期前的秒数。这个属性仅适用于 JSSE 连接器。默认值为 86400 秒,也就是 24 小时。
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=session-timeout,value=43200)

10.13. 用于敏感字符串的密码库

10.13.1. 关于保护明码文件里的敏感字符

Web 应用程序和其他部署经常含有明码文件,如 XML 部署描述符,其中包含敏感信息如密码和其他敏感字符串。JBoss EAP 6 包含一个密码库(Password Vault)机制,可以让你加密敏感信息并将其存储在一个加密的密钥库(Keystore)里。这个库机制管理解密用于安全域、安全区或其他验证系统的字符串。这提供了一个额外的安全层。这个机制依赖于被支持的 JKD 实现里包含的一些工具。

警告

我们在 JBoss EAP 6 里使用库安全功能时遇到了问题。在使用 IBM JDK 时,我们发现 vault.keystore 生成的 Sun/Oracle keytool 不是有效的密钥库。这是由于不同的 Java 供应商里 JCEKS 密钥库实现是不同的。
当 Oracle Java 生成的密钥库用于 IBM Java 上的 JBoss EAP 实例时就会出现这个问题。此时服务器不会启动并抛出如下异常:
java.io.IOException: com.sun.crypto.provider.SealedObjectForKeyProtector
目前,唯一的变通办法是在使用 IBM Java 实现的环境里避免用 Oracle keytool 来生成密钥库。

10.13.2. 创建一个 Java 密钥库来存储敏感信息

前提条件

  • keytool 命令必须可用。它时 JRE 提供的命令。请找到这个文件所在的位置,在红帽企业版 Linux 里,它是 /usr/bin/keytool

过程 10.41. 设置 Java 密钥库

  1. 创建一个目录来存储你的密钥库和其他加密的信息。

    创建一个目录来存储你的密钥库和其他加密的信息。这个过程的剩余部分将假设这个目录是 /home/USER/vault/
  2. 确定 keytool 要使用的参数。

    确定下列参数:
    alias
    别名是 vault 或其他存储在密钥库里的数据的唯一标识符。这个过程结尾的命令示例里的别名是 vault。别名是区分大小写的。
    keyalg
    用于加密的算法。这个过程里的例子使用了 RSA。请查看你的 JRE 和操纵系统的文档,看那种选择是可用的。
    keysize
    加密密钥的大小影响了通过 brute force 解密的难度。这个过程里的例子使用了 2048。关于合适的值的信息,请参考 keytool 所附带的文档。
    keystore
    密钥库是一个保存加密信息以及如何解密的信息的数据库。如果你没有指定密钥库,默认的密钥库是你的主目录下的 .keystore。当第一次添加数据到密钥库时,它会被创建。这个过程里的例子使用了 vault.keystore 密钥库。
    keytool 命令有很多其他选项。更多的细节,请参考你的 JRE 或操纵系统的文档。
  3. 确定 keystore 命令会询问的问题的答案。

    keystore 需要下列信息来填充密钥库条目:
    密钥库密码
    当你创建一个密钥库时,你必须设置密码。为了和将来的密钥库一起使用,你需要提供密码。请选择一个你可以记住的强密码。密钥库的安全性取决于密码以及它所在的文件系统和操纵系统的安全性。
    密钥密码(可选)
    除了密钥库密码,你可以为每个保存的密钥指定一个密码。每次使用这个密钥时都需要输入密码。通常这个功能不会被使用。
    名和姓
    这和列表里余下的信息可以有助于唯一标识密钥并将其放入一个其他密钥的层次结构里。它完全可以不是一个名字,但应该是两个单词,而且是唯一的。这个过程里的例子使用了 Accounting Administrator。按照目录的术语,它成为了证书的通用名称(common name)
    机构内部门(Organizational unit)
    这是一个标识谁在使用证书的单词。它可以是应用程序或商业单元。这个过程里的例子使用了AccountingServices。通常,组或应用程序使用的所有密钥库都使用相同的机构内部门。
    机构
    这通常是一个代表你的机构名称的单词。它通常在机构使用的所有证书里都保持相同。这个例子使用了MyOrganization
    城市或自治区
    你的城市
    州或省
    你的州或省,或者相等的地区
    国家
    两个字母的国家代码
    所有这些信息将创建一个密钥库和证书的层次结构,确保它们使用一致而唯一的命名结构。
  4. 运行 keytool 命令,提供你收集的信息。

    例 10.33. keystore 命令的输入和输出的例子。

    $ keytool -genseckey -alias vault -storetype jceks -keyalg AES -keysize 128 -storepass vault22 -keypass vault22 -keystore /home/USER/vault/vault.keystore
    Enter keystore password: vault22 
    Re-enter new password:vault22 
    What is your first and last name?
      [Unknown]:  Accounting Administrator
    What is the name of your organizational unit?
      [Unknown]:  AccountingServices
    What is the name of your organization?
      [Unknown]:  MyOrganization
    What is the name of your City or Locality?
      [Unknown]:  Raleigh
    What is the name of your State or Province?
      [Unknown]:  NC
    What is the two-letter country code for this unit?
      [Unknown]:  US
    Is CN=Accounting Administrator, OU=AccountingServices, O=MyOrganization, L=Raleigh, ST=NC, C=US correct?
      [no]:  yes
    
    Enter key password for <vault>
            (RETURN if same as keystore password):
    
结果

/home/USER/vault/ 目录里创建了一个名为 vault.keystore 的文件。它保存了一个名为 vault 的密钥,这个密钥将为用来为 JBoss EAP 6 保存加密字符串,如密码。

前提条件

  1. 运行 vault.sh 命令。

    运行 EAP_HOME/bin/vault.sh。输入 0 启动新的交互式会话。
  2. 输入保存加密文件的目录。

    这个目录应该比较安全,但 JBoss EAP 6 需要能够访问它。如果你按照 第 10.13.2 节 “创建一个 Java 密钥库来存储敏感信息” 进行,你的密钥库应该位于主目录的 vault/ 里。这个例子使用了目录 /home/USER/vault/

    注意

    不要忘记目录名后面的斜杠。根据操作系统来使用 /\
  3. 输入密钥库的路径。

    输入密钥库文件的完整路径。这个例子使用了 /home/USER/vault/vault.keystore
  4. 加密密钥库的密码。

    下面的步骤加密了密钥库的密码,所以你可以在配置文件和应用程序里安全地使用它了。
    1. 输入密钥库的密码。

      遇到提示时,输入密钥库的密码。
    2. 输入一个 salt 值。

      输入 8 个字符的 salt 值。这个 salt 值和下面的迭代计数用于创建哈希值。
    3. 输入迭代计数。

      输入迭代计数的值。
    4. 记录密码掩码信息。

      密码掩码、salt 和迭代计数都输出在标准输出里。将其记录在一个安全的位置。攻击者可能用它们来破解密码。
    5. 输入 vault 的别名。

      遇到提示时,输入 vault 的别名。如果你按照 第 10.13.2 节 “创建一个 Java 密钥库来存储敏感信息” 来创建 vault,那么别名应该是 vault
  5. 退出交互式控制台。

    输入 2 来退出交互式控制台。
结果

你的密钥库密码已设置掩码,可用于配置文件和部署了。此外,你的 vault 已配置完全且可以使用了。

10.13.4. 配置 JBoss EAP 6 来使用密码库

概述

在你可以在配置文件里为密码设置掩码和其他敏感属性之前,你需要让 JBoss EAP 6 知晓存储和破解密码的密码库。请按照下列步骤来启用这个功能。

过程 10.42. 设置密码库

  1. 确定这个命令的正确的值。

    确定下列参数的值,这个命令将用它们来创建密钥库。关于创建密钥库的信息,请参考下列主题:第 10.13.2 节 “创建一个 Java 密钥库来存储敏感信息”第 10.13.3 节 “设置密钥库密码的掩码并初始化密码库”
    Expand
    参数 描述
    KEYSTORE_URL
    密钥库文件的 URL 的文件系统路径,它通常类似于 vault.keystore
    KEYSTORE_PASSWORD
    用来访问密钥库的密码。这个值应该被标记。
    KEYSTORE_ALIAS
    密钥库的名称。
    SALT
    用来加密和解密密钥库值的 Salt。
    ITERATION_COUNT
    运行加密算法的次数。
    ENC_FILE_DIR
    密钥库命令运行的目录路径。通常是包含密码库的目录。
    host (managed domain only)
    你在配置的主机的名称
  2. 使用管理 CLI 来启用密码库。

    根据使用的是受管域还是独立服务器配置,分别运行下列命令。用这个步骤里第一步里的值替换命令里的值。

    注意

    如果你使用的是 Microsoft Windows 服务器,请用 4 个 \ 字符替换文件或目录里的每个 / 字符。这是因为它需要两个 \ 来作为脱字符。对于其他 / 字符则不需要这么做。
    • 受管域

      /host=YOUR_HOST/core-service=vault:add(vault-options=[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])
      
    • 独立服务器

      /core-service=vault:add(vault-options=[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])
      
    下面是带有假定值的命令示例:
    /core-service=vault:add(vault-options=[("KEYSTORE_URL" => "/home/user/vault/vault.keystore"), ("KEYSTORE_PASSWORD" => "MASK-3y28rCZlcKR"), ("KEYSTORE_ALIAS" => "vault"), ("SALT" => "12438567"),("ITERATION_COUNT" => "50"), ("ENC_FILE_DIR" => "/home/user/vault/")])
    
结果

JBoss EAP 6 已配置好通过密码库来破解掩码字符串。要添加字符串到库里并在配置里使用它们,请参考下列主题:第 10.13.5 节 “在 Java 密钥库里保存和获取加密的敏感字符串”

总结

在普通文本配置文件里包含密码和其他敏感字符串是不安全的。JBoss EAP 6 包括了在加密的密钥库里存储并为这些敏感字符串设置掩码,以及在配置文件里使用掩码值。

过程 10.43. 设置 Java 密钥库

  1. 运行 vault.sh 命令。

    运行 EAP_HOME/bin/vault.sh。输入 0 启动新的交互式会话。
  2. 输入保存加密文件的目录。

    如果你遵循 第 10.13.2 节 “创建一个 Java 密钥库来存储敏感信息”,你的密钥库将位于主目录里的 vault/ 下。在多数情况下,将所有加密信息保存在相同的位置是有意义的。这个例子使用了 /home/USER/vault/

    注意

    不要忘记目录名后面的斜杠。根据操作系统来使用 /\
  3. 输入密钥库的路径。

    输入密钥库文件的完整路径。这个例子使用了 /home/USER/vault/vault.keystore
  4. 输入密钥库密码、Vault 名、Sale 和迭代计数。

    遇到提示时,输入密钥库密码、Vault 名、Sale 和迭代计数。然后将执行握手操作。
  5. 选择保存密码的选项。

    选择选项 0 来保存密码或其他敏感字符串。
  6. 输入这个值。

    遇提示时,将这个值输入两次。如果两次的值不匹配,会提示你再次输入。
  7. 输入 Vault Block。

    输入 Vault Block,
  8. 输入属性名称。

    输入你在保存的属性的名称。一个例子就是 password
    结果

    类似于下面的信息表示这个属性已经被保存了。

    Attribute Value for (ds_ExampleDS, password) saved
  9. 记录关于加密字符串的信息。

    标准输出的信息将显示 vault block、属性名称、共享密钥和在配置里使用字符串的建议。请在安全的地方记录这些信息。下面是输出示例。
    ********************************************
    Vault Block:ds_ExampleDS
    Attribute Name:password
    Configuration should be done as follows:
    VAULT::ds_ExampleDS::password::1
    ********************************************
    
  10. 在你的配置里使用加密的字符串。

    在你的配置里使用前面步骤里的字符串来替代普通文本字符串。下面是使用加密密码的数据源。
    ...
      <subsystem xmlns="urn:jboss:domain:datasources:1.0">
        <datasources>
          <datasource jndi-name="java:jboss/datasources/ExampleDS" enabled="true" use-java-context="true" pool-name="H2DS">
            <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
            <driver>h2</driver>
            <pool></pool>
            <security>
              <user-name>sa</user-name>
              <password>${VAULT::ds_ExampleDS::password::1}</password>
            </security>
          </datasource>
          <drivers>
             <driver name="h2" module="com.h2database.h2">
                <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
             </driver>
          </drivers>
        </datasources>
      </subsystem>
    ...
    
    
    你可以在允许表达式的任何域或独立配置文件里使用加密字符串。

    注意

    要检查某个子系统里是否允许表达式,请在这个子系统里运行下列 CLI 命令:
    /host=master/core-service=management/security-realm=TestRealm:read-resource-description(recursive=true)
    在这个命令的输出里,查找 expressions-allowed 参数的值。如果它为 true,你可以在这个特定子系统的配置里使用表达式。
    在密钥库里保存了字符串后,请使用下列语法用加密字符串替代任何明文字符串。
    ${VAULT::<replaceable>VAULT_BLOCK</replaceable>::<replaceable>ATTRIBUTE_NAME</replaceable>::<replaceable>ENCRYPTED_VALUE</replaceable>}
    
    下面是一个例子,其 Vault Block 是 ds_ExampleDS,而属性是 password
    <password>${VAULT::ds_ExampleDS::password::1}</password>
    

10.13.6. 存储和解析应用程序里的敏感字符串

概述

JBoss EAP 6 的 Configuration 元素支持使用安全库(Security Vault)机制根据 Java 密钥库里保存的值来解析加密的字符串。你可以在自己的应用程序里添加对这个功能的支持。

首先,添加这个密码到库里。然后,用保存在库的密码替换明文密码。你可以使用这个方法来隐藏应用程序里的任何敏感字符串。
前提条件

在执行这个过程之前,请确保保存库文件的目录是存在的。将其保存在什么位置是无所谓的,只要执行 JBoss EAP 6 的用户有读写这些文件的权限。这个例子将 vault/ 目录放到 /home/USER/vault/ 目录里。这个库本身也是 vault/ 里一个名为 vault.keystore 的文件。

例 10.34. 添加密码字符串到库里

请用 EAP_HOME/bin/vault.sh 命令添加这个字符串到库里。下面的屏幕输出包含了这个命令的完整过程和结果。用户输入的值被高亮显示。出于格式的考虑,我们删除了一些输出。在 Microsoft Windows 里,这个命令是 vault.bat。请注意,在 Microsoft Windows 里,文件路径要使用 \ 来分隔,而不是 /
[user@host bin]$ ./vault.sh 
**********************************
****  JBoss Vault ********
**********************************
Please enter a Digit::   0: Start Interactive Session  1: Remove Interactive Session  2: Exit
0
Starting an interactive session
Enter directory to store encrypted files:/home/user/vault/
Enter Keystore URL:/home/user/vault/vault.keystore
Enter Keystore password: ...
Enter Keystore password again: ...
Values match
Enter 8 character salt:12345678
Enter iteration count as a number (Eg: 44):25

Enter Keystore Alias:vault
Vault is initialized and ready for use
Handshake with Vault complete
Please enter a Digit::   0: Store a password  1: Check whether password exists  2: Exit
0
Task:  Store a password
Please enter attribute value: sa
Please enter attribute value again: sa
Values match
Enter Vault Block:DS
Enter Attribute Name:thePass
Attribute Value for (DS, thePass) saved

Please make note of the following:
********************************************
Vault Block:DS
Attribute Name:thePass
Configuration should be done as follows:
VAULT::DS::thePass::1
********************************************

Please enter a Digit::   0: Store a password  1: Check whether password exists  2: Exit
2
将被加入到 Java 代码里的字符串是输出结果里最后面的值,就是以 VAULT 开始的行。
下列 servlet 使用了 vaulted 字符串而不是明文密码。明文版本被注释了,你可以看到其中的区别。

例 10.35. 使用 vaulted 密码的 servlet

package vaulterror.web;
 
import java.io.IOException;
import java.io.Writer;
 
import javax.annotation.Resource;
import javax.annotation.sql.DataSourceDefinition;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.sql.DataSource;
 
 
/*@DataSourceDefinition(
        name = "java:jboss/datasources/LoginDS",
        user = "sa",
        password = "sa",
        className = "org.h2.jdbcx.JdbcDataSource",
        url = "jdbc:h2:tcp://localhost/mem:test"
)*/
@DataSourceDefinition(
        name = "java:jboss/datasources/LoginDS",
        user = "sa",
        password = "VAULT::DS::thePass::1",
        className = "org.h2.jdbcx.JdbcDataSource",
        url = "jdbc:h2:tcp://localhost/mem:test"
)
@WebServlet(name = "MyTestServlet", urlPatterns = { "/my/" }, loadOnStartup = 1)
public class MyTestServlet  extends HttpServlet {
 
    private static final long serialVersionUID = 1L;
 
 
    @Resource(lookup = "java:jboss/datasources/LoginDS")
    private DataSource ds;
 
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        Writer writer = resp.getWriter();
        writer.write((ds != null) + "");
    }
}
你的 servlet 现在可以解析 vaulted 字符串了。

10.14. FIPS 140-2 兼容加密

10.14.1. 关于 FIPS 140-2 兼容性

联邦信息处理标准 140-2 ( Federal Information Processing Standard,FIPS 140-2) 是鉴定加密软件模块的美国政府计算机安全标准。FIPS 140-2 兼容性通常是政府机构和私有企业使用的软件系统的要求之一。
JBoss EAP 6 使用了外部的模块加密,你可以配置它使用兼容 FIPS 140-2 的加密模块。

10.14.2. 兼容 FIPS 140-2 的密码

兼容 FIPS 的密码必须具有下列特征:
  1. 其长度必须至少有 7 个字符。
  2. 必须包含来自至少三个下列字符类别里的字符:
    • ASCII 数字
    • 小写的 ASCII 字符
    • 大写的 ASCII 字符
    • 非字母的 ASCII,和
    • 非 ASCII 字符
如果第一个字符是大写的 ASCII 字符,它不会算作限制 2 里的大写 ASCII 字符。
如果密码的最后一个字符是 ASCII 数字,它不会算作限制 2 里的 ASCII 数字。
这个任务描述了如何配置 JBoss EAP 6 的 Web 容器(JBoss Web)的 SSL 为兼容 FIPS 140-2 的加密。这个任务只涵盖在红帽企业版 Linux 6 上实现的步骤。
为了这个功能,这个任务使用了 FIPS 模式的 Mozilla NSS 库。

前提条件

过程 10.44. 启用 SSL 的 FIPS 140-2 兼容加密

  1. 创建数据库

    jboss 用户拥有的一个目录里创建 NSS 数据库。
    $ mkdir -p  /usr/share/jboss-as/nssdb
    $ chown jboss /usr/share/jboss-as/nssdb 
    $ modutil -create -dbdir /usr/share/jboss-as/nssdb
    
  2. 创建 NSS 配置文件

    /usr/share/jboss-as 目录里创建一个名为 nss_pkcsll_fips.cfg 的文本文件,它具有下列内容:
    name = nss-fips
    nssLibraryDirectory=/usr/lib64
    nssSecmodDirectory=/usr/share/jboss-as/nssdb
    nssModule = fips
    
    NSS 配置文件必须指定:
    • 名称
    • NSS 库所在的目录,和
    • 步骤 1 里创建 NSS 数据库用到的目录。
    如果你使用的是红帽企业版 Linux 6 的 64 位版本,请设置 nssLibraryDirectory/usr/lib 而不是 /usr/lib64
  3. 启用 SunPKCS11 供应商

    编辑你的 JRE 的java.security 配置文件( $JAVA_HOME/jre/lib/security/java.security)并添加下列行:
    security.provider.1=sun.security.pkcs11.SunPKCS11  /usr/share/jboss-as/nss_pkcsll_fips.cfg
    
    请注意这一行里指定的配置文件就是我们在步骤 2 里创建的文件。
    这个文件里的任何其他 security.provider.X 行都必须将 X 递增以设置对应供应商的优先级。
  4. 为 NSS 库启用 FIPS 模式

    运行 modutil 命令以启用 FIPS 模式:
    modutil -fips true -dbdir /usr/share/jboss-as/nssdb
    请注意这里指定的目录就是我们在步骤 1 里创建的目录。
    此时你可能遇到一个安全库错误,要求你为某些 NSS 共享对象重新生成库签名。
  5. 修改 FIPS 令牌的密码

    用下列命令在 FIPS 令牌上设置密码。请注意,令牌的名称必须为 NSS FIPS 140-2 Certificate DB
    modutil -changepw "NSS FIPS 140-2 Certificate DB" -dbdir /usr/share/jboss-as/nssdb
    用于 FIPS 令牌的密码必须是兼容 FIPS 的密码。
  6. 使用 NSS 工具创建证书

    输入下列命令来用 NSS 工具创建证书。
    certutil -S -k rsa -n jbossweb  -t "u,u,u" -x -s "CN=localhost, OU=MYOU, O=MYORG, L=MYCITY, ST=MYSTATE, C=MY" -d /usr/share/jboss-as/nssdb
  7. 配置 HTTPS 连接器使用 PKCS11 密钥库

    用 JBoss CLI 工具里的下列命令添加一个 HTTPS 连接器:
    /subsystem=web/connector=https/:add(socket-binding=https,scheme=https,protocol=HTTP/1.1,secure=true)
    
    然后用下列命令添加 SSL 配置,用兼容 FIPS 的密码(参考步骤 5)替换这里的 PASSWORD。
    /subsystem=web/connector=https/ssl=configuration:add(name=https,password=PASSWORD,keystore-type=PCKS11,
    cipher-suite="SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,
    TLS_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_DSS_WITH_AES_128_CBC_SHA,
    TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,
    TLS_DHE_DSS_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,
    TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,
    TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,
    TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,
    TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,
    TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
    TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_anon_WITH_AES_128_CBC_SHA,
    TLS_ECDH_anon_WITH_AES_256_CBC_SHA")
    
  8. 检验

    运行下列命令检验 JVM 是否可以从 PKCS11 密钥库楼里读取私有密钥:
    keytool -list -storetype pkcs11
    

例 10.36. 使用 FIPS 140-2 的 HTTPS 连接器的 XML 配置

<connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true">
  <ssl name="https" password="****" 
      cipher-suite="SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,
         TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA,
         TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,
         TLS_DHE_DSS_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,
         TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,
         TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,
         TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,
         TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,
         TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
         TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
         TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_anon_WITH_AES_128_CBC_SHA,
         TLS_ECDH_anon_WITH_AES_256_CBC_SHA"
      keystore-type="PKCS11"/>
</connector>
请注意,cipher-suite 属性里插入了断行符以便于阅读。

第 11 章 安全管理引用

11.1. 包括的验证模块

JBoss EAP 6 里包含了下面的验证模块。其中一些模块处理授权及验证。它们的 Code 名称通常包含 Role
当配置这些模块时,请使用 Code 值或完整的软件包限定名来引用 module.java。
Expand
表 11.1. Client
代码
Client
分类
org.jboss.security.ClientLoginModule
描述
这个登录模块的目的是当 JBoss EAP 6 充当客户时建立调用者标识符和凭证。它不应该作为用于实际的服务器验证的安全域的一部分。
Expand
表 11.2. 客户模块选项
选项 类型 默认 描述
multi-threaded
truefalse
false
如果每个线程都有自己的 principal 和凭证存储,请将其设置为 true。false 则指定虚拟机里的所有线程都共享系统的标识符和凭证。
password-stacking
useFirstPassfalse
false
设置为 useFirstPass 表示这个登录模块应该寻找存储在 LoginContext 里的信息以用作标识符。当堆积这个登录模块和其他模块时可以使用这个选项。
restore-login-identity
truefalse
false
如果在 login() 方法的开始遇到的标识符和凭证在 logout() 被调用后要重新存储,请将其设置为 true。
Expand
表 11.3. Certificate
代码
Certificate
分类
org.jboss.security.auth.spi.BaseCertLoginModule
描述
这个登录模块的目的是基于 X509 Certificates 验证用户。其中一个用例是 web 应用程序的 CLIENT-CERT 验证。
Expand
表 11.4. Certificate Module Options
选项 类型 默认 描述
securityDomain
具有持有信任证书的信任库的 JSSE 配置的安全域的名称。
verifier
分类
用户登录证书检验的 org.jboss.security.auth.certs.X509CertificateVerifier 的类名。
Expand
表 11.5. CertificateUsers
代码
CertificateUsers
分类
org.jboss.security.auth.spi.UsersRolesLoginModule
描述
使用属性资源。第一个映射用户名和密码,第二个映射用户名和角色。
Expand
表 11.6. CertificateUsers 模块选项
选项 类型 默认 描述
unauthenticatedIdentity
字符串
定义应该分配给不包含验证信息的请求的 principal 名称。这允许不受保护的 servlet 调用不要求专有角色的 EJB 上的方法。这样的 principal 没有关联的角色且只访问未设置安全性的 EJB 或者和 unchecked permission 约束关联的 EJB。
password-stacking
useFirstPassfalse
false
设置为 useFirstPass 表示这个登录模块应该寻找存储在 LoginContext 里的信息以用作标识符。当堆积这个登录模块和其他模块时可以使用这个选项。
hashAlgorithm 字符串
用于 hash 密码的 java.security.MessageDigest 算法的名称。这个选项没有默认值,你必须显性地设置它来启用哈希算法。当指定了哈希算法时,CallbackHandler 里包含的明文密码将在作为 inputPassword 参数传递给 UsernamePasswordLoginModule.validatePassword 前进行 hash。保存在 users.properties 文件里的密码必须进行同等的 hash。关于 java.security.MessageDigest 和这个类支持的算法的更多信息,请参考 http://docs.oracle.com/javase/6/docs/api/java/security/MessageDigest.html
hashEncoding
base64hex
base64
如果设置了 hashAlgorithm,哈希密码的字符串格式。
hashCharset
字符串
容器的环境里的默认编码集。
将明文密码转换为字节队列的编码。
usersProperties
属性文件或资源的全限定文件路径
users.properties
包含用户和密码间映射的文件。这个文件里的每个属性的格式都是 username=password
rolesProperties
属性文件或资源的全限定文件路径
roles.properties
包含用户和密码间角色的文件。这个文件里的每个属性的格式都是 username=role1,role2,...,roleN
ignorePasswordCase
truefalse
false
密码的比较是否应该忽略大小写。当哈希密码不明显时这对于编码是很重要的。
principalClass
全限定类名。
包含一个将 String 参数用作 principal 名称的构造器的 Principal 实现类。
roleGroupSeparator
单个字符
. (单一句号)
用来将用户名从 rolesGroup 文件里的角色组名里分离的字符。
defaultUsersProperties
defaultUsers.properties
如果未找到 usersProperties 文件所使用的资源或文件的名称。
defaultRolesProperties
defaultRoles.properties
如果未找到 rolesProperties 文件所使用的资源或文件的名称。
hashUserPassword
truefalse
true
当指定了 hashAlgorithm 时是否 hash 用户输入的密码。默认为 true
hashStorePassword
truefalse
true
当指定了 hashAlgorithm 时是否 hash 从 getUsersPassword() 返回的存储密码。
digestCallback
全限定类名。
包含 pre 或 post 摘要内容(如 salt 值)的 org.jboss.crypto.digest.DigestCallback 实现的类名。它只有在指定了 hashAlgorithm 时才被使用。
storeDigestCallback
全限定类名。
包含 pre 或 post 摘要内容(如哈希存储密码的 salt 值)的 org.jboss.crypto.digest.DigestCallback 实现的类名。它只有在 hashStorePassword 为 true 且指定了 hashAlgorithm 时才被使用。
callback.option.STRING
不同的
所有以 callback.option. 为前缀的选项都会传递给 DigestCallback.init(Map) 方法。收入用户名总是通过 javax.security.auth.login.name 选项传递的,而输入/存储密码是通过 digestCallbackstoreDigestCallbackjavax.security.auth.login.password 选项来传递的。
Expand
表 11.7. CertificateRoles
代码
CertificateRoles
分类
org.jboss.security.auth.spi.CertRolesLoginModule
描述
这个登录模块扩展了 Certificate 登录模块以从属性文件添加角色映射能力。它使用和 Certificate 登录模块相同的所有选项,并添加了如下选项。
Expand
表 11.8. CertificateRoles 模块选项
选项 类型 默认 描述
rolesProperties
字符串
roles.properties
包含分配给每个用户的资源或文件的名称。角色属性文件里的格式必须是 username=role1,role2,其中 username 是证书的 DN,不包括任何 =(等号)和空格字符。下面的例子是正确的格式:
CN\=unit-tests-client,\ OU\=Red\ Hat\ Inc.,\ O\=Red\ Hat\ Inc.,\ ST\=North\ Carolina,\ C\=US=JBossAdmin
defaultRolesProperties
字符串
defaultRoles.properties
如果未找到 rolesProperties 文件所使用的资源或文件的名称。
roleGroupSeparator
单个字符
. (单一句号)
作为 roleProperties 文件里的角色组分隔符的字符。
Expand
表 11.9. Database
代码 Database
分类
org.jboss.security.auth.spi.DatabaseServerLoginModule
描述
支持验证和角色映射的基于 JDBC 的登录模块。这基于具有下列定义的两个逻辑表。
  • Principals: PrincipalID (text), Password (text)
  • Roles: PrincipalID (text), Role (text), RoleGroup (text)
Expand
表 11.10. Database 模块选项
选项 类型 默认 描述
dsJndiName
JNDI 资源
保存验证信息的 JNDI 资源的名称。这个选项是必需的。
principalsQuery
prepared SQL 语句
select Password from Principals where PrincipalID=?
获取 principal 的信息的 prepared SQL 查询。
rolesQuery
prepared SQL 语句
select Role, RoleGroup from Roles where PrincipalID=?
获取角色信息的 prepared SQL 查询。它应该和 select Role, RoleGroup from Roles where PrincipalID=? 相等,这里的 Role 是角色名称而 RoleGroup 的值总是带有大写 RRolesCallerPrincipal
Expand
表 11.11. DatabaseCertificate
代码
DatabaseCertificate
分类
org.jboss.security.auth.spi.DatabaseCertLoginModule
描述
这个登录模块扩展了 Certificate 登录模块以从数据库表添加角色映射能力。它使用和 Certificate 登录模块相同的所有选项,并添加了如下选项。
Expand
表 11.12. DatabaseCertificate 模块选项
选项 类型 默认 描述
dsJndiName
JNDI 资源
保存验证信息的 JNDI 资源的名称。这个选项是必需的。
rolesQuery
prepared SQL 语句
select Role,RoleGroup from Roles where PrincipalID=?
为了映射角色的 prepared SQL 语句。它应该和 select Role, RoleGroup from Roles where PrincipalID=? 相等,这里的 Role 是角色名称而 RoleGroup 的值总是带有大写 RRolesCallerPrincipal
suspendResume
truefalse
true
在数据库操作期间现有的 JTA 事务是否应该被暂停。
Expand
表 11.13. Identity
代码
Identity
分类
org.jboss.security.auth.spi.IdentityLoginModule
描述
关联这个模块选项里指定的 principal 和任何针对这个模块验证的主题。所使用的 Principal 类的类型是 org.jboss.security.SimplePrincipal。如果没有指定 principal 选项,那使用的名称是 guest
Expand
表 11.14. Identity 模块选项
选项 类型 默认 描述
principal
字符串
guest
用于 principal 的名称。
roles
用逗号隔开的字符串的列表
将分配给主题的用逗号隔开的角色列表。
Expand
表 11.15. Ldap
代码
Ldap
分类
org.jboss.security.auth.spi.LdapLoginModule
描述
当用户名和密码存储在可通过 JNDI LDAP 供应商访问的 LDAP 服务器上时进行的验证。许多选项不是必需的,因为它们可由 LDAP 供应商或系统环境来决定。
Expand
表 11.16. Ldap 模块选项
选项 类型 默认 描述
java.naming.factory.initial
类名
com.sun.jndi.ldap.LdapCtxFactory
InitialContextFactory 实现的类名。
java.naming.provider.url
ldap:// URL
LDAP 服务器的 URL。
java.naming.security.authentication
nonesimple 或 SASL 机制的名称。
simple
用于绑定 LDAP 服务器的安全级别。
java.naming.security.protocol
传输协议
如果未指定,则由供应商决定。
用于安全访问的传输协议,如 SSL。
java.naming.security.principal
字符串
用于验证调用者的 principal 的名称。它是根据下面描述的属性构建的。
java.naming.security.credentials
凭证类型
验证模式使用的凭证类型。其中一些例子包括哈希密码、明文密码、密钥或证书。如果没有指定这个属性,其行为将由服务供应商决定。
principalDNPrefix
字符串
添加到用户名以组成用户 DN 的前缀。你可以提示用户输入用户名并使用 principalDNPrefixprincipalDNSuffix 构建全限定 DN。
principalDNSuffix
添加到用户名以组成用户 DN 的后缀。你可以提示用户输入用户名并使用 principalDNPrefixprincipalDNSuffix 构建全限定 DN。
useObjectCredential
truefalse
false
凭证是否应该用 org.jboss.security.auth.callback.ObjectCallback 类型的回调方法作为不透明的对象、还是用 JAAS PasswordCallback 作为字符数组密码获得。这允许传递非字符数组的凭证信息到 LDAP 服务器。
rolesCtxDN
全限定的 DN
用于搜索用户角色的上下文的全限定 DN。
userRolesCtxDNAttributeName
属性
包含搜索用户角色的上下文 DN 的用户对象里的属性。它和 rolesCtxDN 的区别是搜索用户角色的上下文可能对于每个用户都是唯一的。
roleAttributeID
属性
roles
包含用户角色的属性的名称。
roleAttributeIsDN
truefalse
false
roleAttributeID 是否包含角色对象的全限定 DN。如果为 false,角色名将从上下文名称的 roleNameAttributeId 属性值里获取。某些目录模式,如 Microsoft Active Directory,要求这个属性的值为 true
roleNameAttributeID
属性
group
包含角色名称的 roleCtxDN 上下文里的属性的名称。如果 roleAttributeIsDN 属性为 true,这个属性将被用来查找角色对象的 name 属性。
uidAttributeID
属性
uid
UserRolesAttributeDN 里对应用户 ID 的属性的名称。它被用来定位用户角色。
matchOnUserDN
truefalse
false
对用户角色搜索是否应该匹配用户的全限定 DN 或只是用户名而已。如果为true,完整的用户 DN 将作为匹配值。如果为 false,则只使用用户名来匹配 uidAttributeName 属性。
allowEmptyPasswords
truefalse
true
是否允许空的密码。多数 LDAP 服务器将空密码视同匿名登录尝试。要拒绝空密码,请将它设置为 false。
Expand
表 11.17. LdapExtended
代码
LdapExtended
分类
org.jboss.security.auth.spi.LdapExtLoginModule
描述
另外的一个使用搜索来定位绑定用户和关联角色的 LDAP 登录模块实现。角色队列递归地解析 DN 来导航分层的角色结构。它使用和 LDAP 模块相同的 java.naming 选项以及下列 LDAP 模块没有的选项。
这个验证以两步进行:
  1. 对 LDAP 服务器的初始绑定是使用 bindDN 和 bindCredential 选项来完成的。bindDN 是一个具有搜索 baseCtxDN 和 rolesCtxDN 树里的用户和角色能力的 LDAP 用户。要验证的用户 DN 是通过 baseFilter 属性指定的过滤器来进行查询的。
  2. 结果用户 DN 是通过将用户 DN 作为 InitialLdapContext 环境的 Context.SECURITY_PRINCIPAL 绑定到 LDAP 服务器来验证的。Context.SECURITY_CREDENTIALS 属性被设置为回调处理程序获得的 String 型的密码。
Expand
表 11.18. LdapExtended 模块选项
选项 类型 默认 描述
baseCtxDN
全限定的 DN
开始用户搜索的顶层上下文的固定 DN。
bindDN
全限定的 DN
用户和角色查询里用来绑定 LDAP 服务器的 DN。这个 DN 需要读取和搜索 baseCtxDNrolesCtxDN 值上的权限。
bindCredential
字符串,可以进行加密。
bindDN 的密码以明文存储,或者用 EXT 命令从外部夹在。这个密码可以用 Vault 机制进行加密。你可以使用下列格式:
  • {EXT}... 这里的 ... 是要求的外部命令。例如:{EXT}cat /mysecretpasswordfile
  • {EXTC[:expiration_in_millis]}... 这里的 ... 是传给 Runtime.exec(String) 方法来执行平台命令的命令。命令输出的第一行被用作密码。
    EXTC 缓存密码 expiration_in_millis 毫秒。 默认的缓存超时时间是 0,也就是无限期。
  • {CLASS}classname[:ctorargs] 里的 [:ctorargs] 是一个由 : 隔开的选项,它将传入 classname ctorctorargs 自身就是一个用逗号隔开的字符串列表。
    密码是通过调用 char[] toCharArray() 方法从 classname 里得到的,否则将使用 String toString()
参考下面的主题里关于加密敏感字符串的内容: 第 10.13.2 节 “创建一个 Java 密钥库来存储敏感信息”
baseFilter
LDAP 过滤器字符串
用来定位要验证的用户的上下文的搜索过滤器。从登录模块回调方法里获得的输入用户名或用户 DN 将替换至过滤器里的 {0} 表达式。搜索过滤器的一个常见例子是 (uid={0})
rolesCtxDN
全限定的 DN
用于搜索用户角色的上下文的固定 DN。这不是实际角色的 DN,它是包含用户角色的对象所在的 DN。例如,在 Microsoft Active Directory 服务器里,它是用户帐号所在的 DN。
roleFilter
LDAP 过滤器字符串
用来定位和验证用户相关联的角色的搜索过滤器。从登录模块回调方法里获得的输入用户名和用户 DN 将被替换过滤器里的 {0} 表达式。已验证的用户 DN 将替换过滤器里的 {1} 表达式。匹配输入用户名的搜索过滤器示例是 (member={0})。对应已验证的用户 DN 的例子是 (member={1})
roleAttributeIsDN
truefalse
false
roleAttributeID 是否包含角色对象的全限定 DN。如果为 false,角色名将从上下文名称的 roleNameAttributeId 属性值里获取。某些目录模式,如 Microsoft Active Directory,要求这个属性的值为 true
defaultRole
角色名称
用于所有已验证用户的角色
parseRoleNameFromDN
truefalse
false
指定查询返回的 DN 是否包含 roleNameAttributeID。如果设置为 true,将检查 DN 里是否有 roleNameATtributeID,如果为 false,将不会检查。这个标记可以提高 LDAP 查询的性能。
parseUsername
truefalse
false
指定 DN 是否对用户名进行解析的标记。如果为 true,DN 将对用户名进行解析。如果为 false,DN 将不对用户名进行解析。这个选项是和 usernameBeginString 及 usernameEndString 一起使用的。
usernameBeginString
字符串
定义将从 DN 的开头删除以显示用户名的字符串。这个选项是和 usernameEndString 一起使用的。
usernameEndString
字符串
定义将从 DN 的结尾删除以显示用户名的字符串。这个选项是和 usernameBeginString 一起使用的。
roleNameAttributeID
属性
group
包含角色名称的 roleCtxDN 上下文里的属性的名称。如果 roleAttributeIsDN 属性为 true,这个属性将被用来查找角色对象的 name 属性。
distinguishedNameAttribute
属性
distinguishedName
包含用户 DN 的用户条目里的属性的名称。如果用户自身的 DN 包含特殊字符(如反斜杠)而阻止了正确的用户映射,这就是有必要的。如果这个属性不存在,条目的 DN 将会被使用。
roleRecursion
整数
0
角色搜索的递归级别数。禁用递归可将其设置为 0
searchTimeLimit
整数
10000 (10 秒)
用户或角色搜索的超时时间(毫秒)。
searchScope
OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE 中的一个
SUBTREE_SCOPE
使用的搜索作用域
allowEmptyPasswords
truefalse
true
是否允许空的密码。多数 LDAP 服务器将空密码视同匿名登录尝试。要拒绝空密码,请将它设置为 false。
Expand
表 11.19. RoleMapping
代码
RoleMapping
分类
org.jboss.security.auth.spi.RoleMappingLoginModule
描述
映射作为验证过程的最终结果的角色到声明式角色。当你添加这个模块到安全域里时,它必须标记为 optional
Expand
表 11.20. RoleMapping 模块选项
选项 类型 默认 描述
rolesProperties
属性文件或资源的全限定文件路径
roles.properties
映射角色到替代角色的属性文件或资源的全限定文件路径。其格式是 original_role=role1,role2,role3
replaceRole
truefalse
false
是否添加当前的角色,或者用映射的角色替换当前的角色。设为 true 则进行替换。
Expand
表 11.21. RunAs
代码
RunAs
分类
Class: org.jboss.security.auth.spi.RunAsLoginModule
描述
这是一个 Helper 模块,它在验证的登录阶段将 run as 角色推入栈,并在提交或中止阶段从栈里弹出 run as 角色。这个登录模块为其他必须访问安全资源以执行验证的登录模块(如访问安全 EJB 的登录模块)提供了一个角色。在要求 run as 角色的登录模块建立之前,你必须先配置好 RunAsLoginModule
Expand
表 11.22. RunAs 选项
选项 类型 默认 描述
roleName
角色名称
nobody
在登录阶段用作 run as 角色的角色的名称。
Expand
表 11.23. Simple
代码
Simple
分类
org.jboss.security.auth.spi.SimpleServerLoginModule
描述
用于测试目的的快速设置安全性的模块。它实现了下列简单的算法:
  • 如果密码为 null,验证用户并分配一个 guest 标识符和 guest 角色。
  • 否则,如果密码和用户相同,分配一个和用户名相同的标识符以及 adminguest 角色。
  • 否则,验证将会失败。
Simple 模块选项

Simple 模块没有选项。

Expand
表 11.24. ConfiguredIdentity
代码
ConfiguredIdentity
分类
org.picketbox.datasource.security.ConfiguredIdentityLoginModule
描述
关联这个模块选项里指定的 principal 和任何针对这个模块验证的主题。所使用的 Principal 类的类型是 org.jboss.security.SimplePrincipal
Expand
表 11.25. ConfiguredIdentity 模块选项
选项 类型 默认 描述
principal
principal 的名称。
none
将和针对这个模块验证的任何主题关联的 principal。
Expand
表 11.26. SecureIdentity
代码
SecureIdentity
分类
org.picketbox.datasource.security.SecureIdentityLoginModule
描述
提供这个模块只是为了和之前的系统兼容。它允许你加密密码并和静态 principal 一起使用这个密码。如果你的应用程序使用了 SecureIdentity,请考虑使用密码库机制。
Expand
表 11.27. SecureIdentity 模块选项
选项 类型 默认 描述
username
用于验证的用户名。
password
加密的字符串
用于验证的密码。要加密这个密码,请在命令行直接使用这个模块。
java org.picketbox.datasource.security.SecureIdentityLoginModule password_to_encrypt
将这个命令的运行结果粘贴到模块选项的 value 字段。
managedConnectionFactoryName
JCA 资源
数据源的 JCA 连接工厂的名称。
Expand
表 11.28. PropertiesUsers
代码
PropertiesUsers
分类
org.jboss.security.auth.spi.PropertiesUsersLoginModule
描述
使用一个属性文件来存储用户名和密码。它没有提供授权(角色映射)。这个模块只适合于测试用途。
Expand
表 11.29. SimpleUsers
代码
SimpleUsers
分类
org.jboss.security.auth.spi.SimpleUsersLoginModule
描述
这个登录模块在一个 Java 属性文件里保存了用户名和明文密码。这只是用于测试目的,不适合用于产品环境里。
Expand
表 11.30. SimpleUsers 模块选项
选项 类型 默认 描述
username
用于验证的用户名。
password
用于验证的明文密码。
Expand
表 11.31. LdapUsers
代码
LdapUsers
分类
org.jboss.security.auth.spi.LdapUsersLoginModule
描述
LdapUsers 模块被 ExtendedLDAPAdvancedLdap 模块取代。
Expand
表 11.32. Kerberos
代码
Kerberos
分类
com.sun.security.auth.module.Krb5LoginModule
描述
用 GSSAPI 执行Kerberos 登录验证。这个模块不是 Sun Microsystems 提供的 API 里的安全框架的一部分。细节可以在 http://docs.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html 里找到。这个模块需要和另外一个处理验证和角色映射的模块配对。
Expand
表 11.33. Kerberos 模块选项
选项 类型 默认 描述
storekey
truefalse
false
是否添加 KerberosKey 到主题的私有凭证。
doNotPrompt
truefalse
false
如果设置为 true,用户将不会被提示输入密码。
useTicketCache
布尔值,truefalse
.
false
如果为 true,GTG 将从票据缓存里获取。如果为 false,将不会使用票据缓存。
ticketcache
代表 Kerberos 票据缓存的文件或资源。
默认值取决于你所使用的操作系统。
  • 红帽企业版 Linux / Solaris: /tmp/krb5cc_uid,使用操作系统的数字 UID 值。
  • Microsoft Windows Server: 使用 Local Security Authority (LSA) API 来查找票据缓存。
票据缓存的位置。
useKeyTab
truefalse
false 是否从密钥表文件里获取 principal 的密钥。
keytab
代表 Kerberos keytab 的文件或资源。
操作系统的 Kerberos 配置文件的位置,或者 /home/user/krb5.keytab
密钥表文件的位置。
principal
字符串
Principal 的名称。这可以是简单的用户名或服务名,如 host/testserver.acme.com。或者当密钥表包含多个 principal 时,使用它而不是从密钥表里获取 principal。
useFirstPass
truefalse
false
是否以从 javax.security.auth.login.namejavax.security.auth.login.password 为关键字从模块的共享状态获取用户名和密码。如果验证失败,不会进行重试。
tryFirstPass
truefalse
false
useFirstPass 相同,但如果验证失败,模块将使用 CallbackHandler 来获取新的用户名和密码。如果第二次验证失败,将报告给调用的应用程序。
storePass
truefalse
false
是否在模块的共享状态里保存用户名和密码。如果关键字已存在于共享内存里,或者验证失败的话,这都不会发生。
clearPass
truefalse
false
设置它为 true 在两个验证阶段都完成后从共享内存里清除用户名和密码。
Expand
表 11.34. SPNEGOUsers
代码
SPNEGOUsers
分类
org.jboss.security.negotiation.spnego.SPNEGOLoginModule
描述
允许在 Microsoft Active Directory 服务器或其他支持 SPNEGO 的环境里进行 SPNEGO 验证。SPNEGO 也可以包含 Kerberos 凭证。这个模块需要和另外一个处理验证和角色映射的模块配对。
Expand
表 11.35. SPNEGO 模块选项
选项 类型 默认 描述
storeKey
truefalse
false
是否保存密钥。
useKeyTab
truefalse
false
是否使用密钥表。
principal
代表 Kerberos 验证的 principal 的字符串。
用于验证的 principal 的名称。
keyTab
代表 keytab 的文件或资源。
none
密钥表的位置。
doNotPrompt
truefalse
false
是否提示输入密码。
debug
truefalse
false
是否记录更冗余的信息以用于调试。
Expand
表 11.36. AdvancedLdap
代码 AdvancedLdap
分类
org.jboss.security.negotiation.AdvancedLdapLoginModule
描述
提供额外功能的模块,如 SASL 和对 JAAS 安全域的使用。
Expand
表 11.37. AdvancedLdap 模块选项
选项 类型 默认 描述
bindAuthentication
用于绑定到目录服务器的 SASL 验证的类型。
java.naming.provider.url
string
目录服务器的 URI.
baseCtxDN
全限定标识名(DN)。
要用作搜索基础的标识名。
baseFilter
代表 LDAP 搜索过滤器的字符串。
用于缩减搜索结果的过滤器。
roleAttributeID
代表 LDAP 属性的字符串。
包含授权角色的名称的 LDAP 属性。
roleAttributeIsDN
truefalse
false
这个角色属性是否是标识名(Distinguished Name,DN)。
roleNameAttributeID
代表 LDAP 属性的字符串。
包含实际角色属性的 RoleAttributeId 里所包含的属性。
recurseRoles
truefalse
false
是否递归地搜索 RoleAttributeId 里的角色。
Expand
表 11.38. AdvancedADLdap
代码 AdvancedADLdap
分类
org.jboss.security.negotiation.AdvancedADLoginModule
描述
这个模块扩展了 AdvancedLdap 登录模块,并添加额外的和 Microsoft Active Directory 相关的参数。
Expand
表 11.39. UsersRoles
代码 UsersRoles
分类
org.jboss.security.auth.spi.UsersRolesLoginModul
描述
支持存储在两个不同属性文件里的多个用户和角色的简单登录模块。
Expand
表 11.40. UsersRoles 模块选项
选项 类型 默认 描述
usersProperties
文件或资源的路径。
users.properties
包含用户-密码映射的文件或资源。这个文件的格式是 user=hashed-password
rolesProperties
文件或资源的路径。
roles.properties
包含用户-角色映射的文件或资源。这个文件的格式是 username=role1,role2,role3
password-stacking
useFirstPassfalse
false
useFirstPass 的值表示这个登录模块应该首先查看存储在 LoginContext 里关于这个标识符的信息。当堆积这个登录模块和其他模块时可以使用这个选项。
hashAlgorithm
代表密码的哈希算法的字符串。
none
用于 hash 密码的 java.security.MessageDigest 算法的名称。这个选项没有默认值,你必须显性地设置它来启用哈希算法。当指定了 hashAlgorithm 时,CallbackHandler 里包含的明文密码将在作为 inputPassword 参数传递给 UsernamePasswordLoginModule.validatePassword 前进行 hash。保存在 users.properties 文件里的密码必须进行同等的 hash。
hashEncoding
base64hex
base64
如果设置了 hashAlgorithm,哈希密码的字符串格式。
hashCharset
字符串
容器的运行时环境里的默认编码集。
将明文密码转换为字节队列的编码。
unauthenticatedIdentity
principal 名称
定义分配给不包含验证信息的请求的 principal 名称。这允许不受保护的 servlet 调用不要求专有角色的 EJB 上的方法。这样的 principal 没有关联的角色且只访问未设置安全性的 EJB 或者和 unchecked permission 约束关联的 EJB。
自定义验证模块

验证模块是 javax.security.auth.spi.LoginModule 的实现。关于创建自定义验证模块的更多信息,请参考相关的 API 文档。

11.2. 包括的授权模块

下面的模块提供授权服务。
Expand
代码
DenyAll org.jboss.security.authorization.modules.AllDenyAuthorizationModule
PermitAll org.jboss.security.authorization.modules.AllPermitAuthorizationModule
Delegating org.jboss.security.authorization.modules.DelegatingAuthorizationModule
Web org.jboss.security.authorization.modules.WebAuthorizationModule
JACC org.jboss.security.authorization.modules.JACCAuthorizationModule

11.3. 包括的安全映射模块

JBoss EAP 6 提供了下面的安全映射角色。
Expand
代码 分类
PropertiesRoles org.jboss.security.mapping.providers.role.PropertiesRolesMappingProvider
SimpleRoles org.jboss.security.mapping.providers.role.SimpleRolesMappingProvider
DeploymentRoles org.jboss.security.mapping.providers.DeploymentRolesMappingProvider
DatabaseRoles org.jboss.security.mapping.providers.role.DatabaseRolesMappingProvider
LdapRoles org.jboss.security.mapping.providers.role.LdapRolesMappingProvider

11.4. 包括的安全审计供应商模块

JBoss EAP 提供了一个安全审计供应商。
Expand
代码 分类
LogAuditProvider org.jboss.security.audit.providers.LogAuditProvider

第 12 章 子系统配置

12.1. 子系统配置概述

简介

JBoss EAP 6 使用了简化的配置,对每个域或独立服务器使用一个配置文件。在独立域里,为每个主机控制器配备一个单独的文件。对配置的修改会自动持久化,所以您不要手动编辑 XML。管理 API 将自动扫描和覆盖配置。基于命令行的管理 CLI 和基于 Web 的管理控制台允许您配置 JBoss EAP 6 的每个方面。

JBoss EAP 6 构建在模块化类加载的概念上。平台提供的每个 API 或服务都实现为模块,再根据需要进行加载和卸载。大多数模块都包含一个配置元素,名为子系统(subsystem)。子系统配置信息保存在统一的配置文件 EAP_HOME/domain/configuration/domain.xml(受管域)或 EAP_HOME/standalone/configuration/standalone.xml(独立服务器)里。许多子系统都包括通过之前 JBoss EAP 版本的部署描述符配置的配置细节。
子系统配置模式

每个子系统的配置都是在 XML Schema 里定义的。配置模式位于 JBoss 的 EAP_HOME/docs/schema/ 目录里。

下面的子系统被称为 simple subsystems,因为它们没有任何可配置的属性或元素。它们通常列在配置文件的顶部。

简单子系统

  • ee– Java EE 6 API 实现
  • ejb– Enterprise JavaBeans (EJB) 子系统
  • jaxrs– RESTeasy 提供的 JAX-RS API
  • sar– 支持 Service Archives 的子系统
  • threads– 支持进程线程的子系统
  • weld– Weld 提供的上下文和依赖关系注入的 API

第 13 章 日志子系统

13.1. 简介

13.1.1. 日志概述

JBoss EAP 6 提供了高度可配置的日志功能以用于内部或应用程序。日志子系统基于 JBoss LogManager,它还支持 JBoss Logging 以外的几个第三方应用程序日志框架。
日志子系统是通过日志类别和处理程序体系来进行配置的。日志类别(Category)定义了要记录哪些消息,而日志处理程序(Handler)则定义如何处理这些消息(写入到磁盘、发送到控制台等)。
日志配置集(Logging Profile)是 6.1.0 版本里添加的功能,它允许创建日志配置的唯一名称并分配给不依赖其他日志配置的应用程序。日志配置集的配置和主日志子系统的配置基本上是一样的。
所有的配置都可以通过管理控制台或 CLI 工具来完成。

13.1.2. JBoss LogManager 支持的应用程序日志框架

JBoss LogManager 支持下列日志框架:

13.1.3. 配置引导日志

引导日志( JBoss Logging)记录服务器启动(或"引导")时发生的事件。
引导日志可以通过编辑 logging.properties 文件来配置。这个文件是一个标准的 Java 属性文件,可以在文本编辑器里进行编辑。这个文件里的每一行的格式都是 property=value
根据您是否以受管域还是独立服务器运行 JBoss EAP 6,logging.properties 文件的完整路径是 EAP_HOME/domain/configuration/logging.propertiesEAP_HOME/standalone/configuration/logging.properties

13.1.4. 默认的日志文件位置

这些日志文件是为默认的日志配置创建的。默认的配置使用定时日志处理程序写入到服务器日志文件里。
Expand
表 13.1. 独立服务器的默认日志文件
日志文件 描述
EAP_HOME/standalone/log/server.log
服务器日志包含了所有的服务器日志消息,其中包括服务器启动消息。
Expand
表 13.2. 受管域的默认日志文件
日志文件 描述
EAP_HOME/domain/log/host-controller.log
主机控制器引导日志包含和主机控制器启动相关的日志消息。
EAP_HOME/domain/log/process-controller.log
进程控制器引导日志包含和进程控制器启动相关的日志消息。
EAP_HOME/domain/servers/SERVERNAME/log/server.log
名为 server. 的服务器日志包含了所有的服务器日志消息,其中包括服务器启动消息。

13.1.5. 日志的过滤器表达式

Expand
表 13.3. 日志的过滤器表达式
过滤器类型
表达式
描述 参数
Accept
accept
接受所有日志消息
accept
Deny
deny
拒绝所有日志消息
deny
Not
not[filter expression]
返回过滤器表达式的相反值
将单一过滤器表达式用作参数
not(match("JBAS"))
All
all[filter expression]
返回来自多个过滤器表达式的串联值
使用多个用逗号隔开的过滤器表达式
all(match("JBAS"),match("WELD"))
Any
any[filter expression]
返回一个来自多个过滤器表达式的值。
使用多个用逗号隔开的过滤器表达式
any(match("JBAS"),match("WELD"))
Level Change
levelChange[level]
用指定的级别修改日志记录
以单个字符串级别为参数
levelChange("WARN")
Levels
levels[levels]
用列表里的级别过滤日志消息
以用逗号隔开的基于多个字符串的级别为参数
levels("DEBUG","INFO","WARN","ERROR")
Level Range
levelRange[minLevel,maxLevel]
过滤指定级别范围内的日志消息
过滤器表达式使用 "[" 来指定最小包含级别以及用 "]" 指定最大包含级别。 或者可以使用 "(" 或 ")" 来指定排除的级别。这个表达式的第一个参数是允许的最小级别,第二是允许的最大级别。
  • 最小级别必须小于 ERROR,而最大级别必须大于 DEBUG。
    levelRange("ERROR","DEBUG")
  • 最小级别必须小于或等于 ERROR,而最大级别必须大于 DEBUG。
    levelRange["ERROR","DEBUG")
  • 最小级别必须小于或等于 ERROR,而最大级别必须大于或等于 DEBUG。
    levelRange["ERROR","INFO"]
Match (match["pattern"]) 基于常规表达式的过滤器。根据表达式里的指定的模式使用未格式化的消息。
以常规表达式为参数
match("JBAS\d+")
Substitute (substitute["pattern","replacement value"]) 这个过滤器用文本替换第一个匹配的模式
这个表达式的第一个参数是模式,而第二个参数是替换文本
substitute("JBAS","EAP")
Substitute All (substituteAll["pattern","replacement value"]) 这个过滤器用文本替换所有匹配的模式
这个表达式的第一个参数是模式,而第二个参数是替换文本
substituteAll("JBAS","EAP")

13.1.6. 关于日志级别

日志级别是一系列排序的枚举值,表示日志消息的性质和严重性。给定日志消息的级别是开发人员用所选的日志框里合适的方法指定的。
JBoss EAP 6 支持受支持的应用日志框架使用的所有日志级别。最常用的 6 个日志级别是(从低到高):TRACE, DEBUG, INFO, WARN, ERRORFATAL
日志类别和处理程序使用日志级别来限制它们负责的日志消息。每个日志级别都分配有一个数值,表示相对于其他日志级别的顺序。日志类别和处理程序分配的日志级别限制它们只成立了该级别或更高级别的消息。例如,级别为 WARN 的日志处理程序只记录级别为 WARNERRORFATAL 的日志消息。

13.1.7. 支持的日志级别

Expand
表 13.4. 支持的日志级别
日志级别 描述
FINEST 300
-
FINER 400
-
TRACE 400
用于提供应用程序运行状态详细信息的消息。TRACE 级别的消息通常在调试应用程序时被捕获。
DEBUG 500
用于指明应用程序的单独请求或活动进度的消息。TRACE 级别的消息通常在调试应用程序时被捕获。
FINE 500
-
CONFIG 700
-
INFO 800
用于表示应用程序总体进度的消息。通常用于应用程序启动、关闭或其他主要的生命周期事件。
WARN 900
用于表示未发生错误但并不理想的情形。它可以表示某些在将来可能导致错误的情形。
WARNING 900
-
ERROR 1000
用于表示已经发生并会阻止当前活动或请求的完成、但不会阻止应用程序运行的错误。
SEVERE 1000
-
FATAL 1100
用于表示可能导致严重服务故障和应用程序关闭及 JBoss EAP 6 关闭的事件。

13.1.8. 关于日志类别

日志类别定义一系列要捕获的日志消息以及处理这些消息的处理程序。
要记录的日志消息是通过它们的原始 Java 软件包和日志级别来定义的。这些软件包里类的消息以及该日志级别或更低级别的消息将按日志类别记录并发送到指定的日志处理程序。
日志类别可以选择使用 Root Logger 的日志处理程序而不是自己的处理程序。

13.1.9. 关于 Root Logger

Root logger 将记录所有发送到服务器而未按照日志列别记录的日志消息(指定级别)。这些消息会被发送到一个或多个日志处理程序。
在默认情况下,我们配置 Root Logger 使用控制台和定期日志处理程序。定期日志处理程序写入文件 server.log。这个文件有时候被称为服务器日志(Server Log)。

13.1.10. 关于日志处理程序

日志处理程序(Log Handler)定义 JBoss EAP 6 如何记录捕获的日志消息。您可以配置 6 种处理程序类型:ConsoleFilePeriodicSizeAsyncCustom

13.1.11. 日志处理程序的类型

Console
Console 处理程序写入日志消息到主机操作系统的标准输出流(stdout)或标准错误流 (stderr)。当通过命令行提示运行 JBoss EAP 6 时会显示这些消息。除非配置操作系统捕获标准输出和标准错误流,来自 Console 日志处理程序的消息不会被保存。
File
File 日志处理程序是最简单的处理程序,它将日志消息写入到指定文件里。
Periodic
Periodic 日志处理程序将日志消息写入到命名文件,直到指定的时间过期。一旦超过指定的时间,文件将通过附件指定的时间戳来改名,而处理程序继续写入到根据原来名称新创建的日志文件。
Size
Size 日志处理程序将日志消息写入到命名文件,直至到达指定的文件大小。一旦超过指定的大小,文件将通过数字前缀改名,而处理程序继续写入到根据原来名称新创建的日志文件。每个 Size 日志处理程序必须指定以这种方式保存的文件的最大数目。
Async
Async 日志处理程序是为一个或多个其他日志处理程序提供异步行为的 Wrapper 日志处理程序。这对于有高延迟性或其他性能问题的日志处理程序来说很有用,例如写入日志文件到网络文件系统。
Custom
Custom 日志处理程序让您可以配置新的日志处理程序类型。Custom 日志处理程序必须实现为继承 java.util.logging.Handler 的 Java 类,并包含在模块里。
syslog
Syslog 处理程序用于发送消息到远程日志服务器。它允许多个应用程序发送它们的日志消息到相同的服务器,一起进行解析。

13.1.12. 关于日志格式器

日志格式器(Log Formatter)是日志处理程序的配置属性,它定义日志消息的外观。它是基于 java.util.Formatter 类的语法的子字符串。
例如 default 配置里的日志格式器 %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n,它创建这样的日志消息:
15:53:26,546 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console listening on http://127.0.0.1:9990

13.1.13. 日志格式器语法

Expand
表 13.5. 日志格式器语法
符号 描述
%c 日志事件的类别
%p 日志条目的级别(INFO/DEBUG/etc)
%P 日志条目的地区级别
%d 当前的日期/时间:date/time (yyyy-MM-dd HH:mm:ss,SSS form)
%r 相对时间(日志被初始化起的毫秒数)
%z 时区
%k 日志资源关键字(用于日志消息的本地化)
%m 日志消息(包含关于异常的跟踪信息)
%s 简单的日志消息(无异常跟踪信息)
%e 异常跟踪信息(无扩展模块信息)
%E 异常跟踪信息(有扩展模块信息)
%t 当前线程的名称
%n 新行符号
%C 调用日志方法(慢速)的代码的类
%F 调用日志方法(慢速)的代码的文件名
%l 调用日志方法(慢速)的代码的位置
%L 调用日志方法(慢速)的代码的行号
%M 调用日志方法(慢速)的代码的方法
%x Log4J 嵌套诊断上下文
%X Log4J 消息诊断上下文
%% 百分比(已完成)

13.2. 在管理控制台里配置日志

管理控制台为 Root Logger、日志处理程序、日志类别的配置提供了图形化用户界面。您可以通过下列步骤在管理控制台里找到日志配置:
您可用下列步骤访问这个配置:
  1. 登录到管理控制台
  2. 进入日志子系统配置。根据服务器是运行于受管域还是独立服务器模式,这个步骤会有所不同。
    • 独立服务器

      点击 Profile 面板,展开 Core 并点击 Logging。
    • 受管域

      点击 Profile 面板,选择要编辑的配置集,展开 Core 并点击 Logging。
您可以配置 Root Logger 的任务是:
  • 编辑级别。
  • 添加和删除日志处理程序。
您可以配置日志类别的任务是;
  • 添加和删除日志级别。
  • 编辑日志类别属性。
  • 从列表里添加和删除日志处理程序。
配置日志处理程序的主要任务是:
  • 添加新的处理程序。
  • 配置处理程序。
所有被支持的 6 个日志处理程序(包括 Custom)都可以在管理控制台里进行配置。

13.3. CLI 里的日志配置

13.3.1. 用 CLI 配置 Root Logger

Root Logger 的配置可以通过 CLI 查看和编辑。
您可以配置 Root Logger 的主要任务是:
  • 在 Root Logger 里添加日志处理程序。
  • 显示 Root Logger 配置。
  • 改变日志级别。
  • 在 Root Logger 里删除日志处理程序。

重要

当在日志配置集里配置 Root Logger 时,配置路径的根目录是 /subsystem=logging/logging-profile=NAME/ 而不是/subsystem=logging/
在 Root Logger 里添加日志处理程序。
请使用 root-logger-assign-handler 操作和下列语法,这里的HANDLER 是要添加的日志处理程序的名称。
 /subsystem=logging/root-logger=ROOT:root-logger-assign-handler(name="HANDLER") 
这个日志处理程序必须在添加到 Root Logger 之前必须已被创建。

例 13.1. Root Logger 的 root-logger-assign-handler 操作

[standalone@localhost:9999 /] /subsystem=logging/root-logger=ROOT:root-logger-assign-handler(name="AccountsNFSAsync")
{"outcome" => "success"}
[standalone@localhost:9999 /]
显示 Root Logger 配置的内容。
使用 read-resource 操作和下列语法。
 /subsystem=logging/root-logger=ROOT:read-resource 

例 13.2. Root Logger 的 read-resource 操作

[standalone@localhost:9999 /] /subsystem=logging/root-logger=ROOT:read-resource                                  
{
   "outcome" => "success",
   "result" => {
      "filter" => {"match" => "names"},
      "handlers" => [
            "CONSOLE",
            "FILE"
      ],
      "level" => "INFO"
   }
}
设置 Root Logger 的日志级别。
请使用 write-attribute 命令和下列语法,这里的 LEVEL 是被支持的日志级别之一。
 /subsystem=logging/root-logger=ROOT:write-attribute(name="level", value="LEVEL") 

例 13.3. 使用 Root Logger 的 write-attribute 操作来设置日志级别

[standalone@localhost:9999 /] /subsystem=logging/root-logger=ROOT:write-attribute(name="level", value="DEBUG")
{"outcome" => "success"}
[standalone@localhost:9999 /]
从 Root Logger 删除日志处理程序。
请使用 root-logger-unassign-handler 操作和下列语法,这里的HANDLER 是要删除的日志处理程序的名称。
 /subsystem=logging/root-logger=ROOT:root-logger-unassign-handler(name="HANDLER") 

例 13.4. 删除日志处理程序

[standalone@localhost:9999 /] /subsystem=logging/root-logger=ROOT:root-logger-unassign-handler(name="AccountsNFSAsync")
{"outcome" => "success"}
[standalone@localhost:9999 /]

13.3.2. 在 CLI 里配置日志类别

您可以在 CLI 里添加、删除和编辑日志类别。
配置日志类别的主要任务是:
  • 添加新的日志类别。
  • 显示日志类别的配置。
  • 设置日志级别。
  • 在日志类别里添加日志程序。
  • 在日志类别里删除日志处理程序。
  • 删除日志类别。

重要

当在日志配置集里配置日志类别时,配置路径的根目录是 /subsystem=logging/logging-profile=NAME/ 而不是/subsystem=logging/
添加日志类别
请使用 write-attribute 命令和下列语法。用日志类别的名称替换 CATEGORY,并用日志级别替换 LEVEL
 /subsystem=logging/logger=CATEGORY:add 

例 13.5. 添加新的日志类别

[standalone@localhost:9999 /] /subsystem=logging/logger=com.company.accounts.rec:add   
{"outcome" => "success"}
[standalone@localhost:9999 /]
显示日志类别配置
请使用 read-resource 命令和下列语法。用日志类别的名称替换 CATEGORY
 /subsystem=logging/logger=CATEGORY:read-resource 

例 13.6. 日志类别的 read-resource 操作

[standalone@localhost:9999 /] /subsystem=logging/logger=org.apache.tomcat.util.modeler:read-resource
{
    "outcome" => "success",
    "result" => {
        "filter" => undefined,
        "handlers" => undefined,
        "level" => "WARN",
        "use-parent-handlers" => true
    }
}
[standalone@localhost:9999 /]
设置日志级别
请使用 write-attribute 命令和下列语法。用日志类别的名称替换 CATEGORY,并用日志级别替换 LEVEL
 /subsystem=logging/logger=CATEGORY:write-attribute(name="level", value="LEVEL") 

例 13.7. 设置日志级别

[standalone@localhost:9999 /] /subsystem=logging/logger=com.company.accounts.rec:write-attribute(name="level", value="DEBUG")
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置日志类别以使用 Root Logger 日志处理程序。
请使用 write-attribute 命令和下列语法。用日志类别的名称替换 CATEGORY。根据这个日志类别是否使用 Root Logger 处理程序用 true 替换 BOOLEAN。如果只使用自己分配的处理程序,则用 false 来代替。
 /subsystem=logging/logger=CATEGORY:write-attribute(name="use-parent-handlers", value="BOOLEAN") 

例 13.8. 设置 use-parent-handlers

[standalone@localhost:9999 /] /subsystem=logging/logger=com.company.accounts.rec:write-attribute(name="use-parent-handlers", value="true")
{"outcome" => "success"}
[standalone@localhost:9999 /]
在日志类别里添加日志程序
请使用 assign-handler 命令和下列语法。用日志类别的名称替换 CATEGORY,并用要添加的处理程序的名称替换 HANDLER
 /subsystem=logging/logger=CATEGORY:assign-handler(name="HANDLER") 
这个日志处理程序必须在添加到 Root Logger 之前必须已被创建。

例 13.9. 添加日志处理程序

[standalone@localhost:9999 /] /subsystem=logging/logger=com.company.accounts.rec:assign-handler(name="AccountsNFSAsync")
{"outcome" => "success"}
[standalone@localhost:9999 /]
在日志类别里删除日志处理程序
请使用 unassign-handler 命令和下列语法。用日志类别的名称替换 CATEGORY,并用要删除的处理程序的名称替换 HANDLER
 /subsystem=logging/logger=CATEGORY:unassign-handler(name="HANDLER") 

例 13.10. 删除日志处理程序

[standalone@localhost:9999 /] /subsystem=logging/root-logger=ROOT:root-logger-unassign-handler(name="AccountsNFSAsync")
{"outcome" => "success"}
[standalone@localhost:9999 /]
删除类别
请使用 remove 命令和下列语法。用要删除的日志类别的名称替换 CATEGORY
 /subsystem=logging/logger=CATEGORY:remove 

例 13.11. 删除日志类别

[standalone@localhost:9999 /] /subsystem=logging/logger=com.company.accounts.rec:remove   
{"outcome" => "success"}
[standalone@localhost:9999 /]

13.3.3. 在 CLI 里配置控制台日志处理程序

您可以在 CLI 里添加、删除和编辑日志处理程序。
配置控制台日志处理程序的主要任务是:
  • 添加新的控制台处理程序
  • 显示控制台日志处理程序的配置。
  • 设置处理程序的日志级别。
  • 设置用于处理程序输出的目标。
  • 设置用于处理程序输出的编码。
  • 设置用于处理程序输出的格式器。
  • 设置处理程序是否使用自动冲刷。
  • 删除控制台日志处理程序。

重要

当在日志配置集里配置日志处理程序时,配置路径的根目录是 /subsystem=logging/logging-profile=NAME/ 而不是/subsystem=logging/
添加控制台处理程序
请使用 add 操作和下列语法,用要添加的日志处理程序的名称替换 HANDLER
 /subsystem=logging/console-handler=HANDLER:add 

例 13.12. 添加控制台处理程序

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:add     
{"outcome" => "success"}
[standalone@localhost:9999 /]
显示控制台日志处理程序的配置
请使用 read-resource 命令和下列语法。用日志处理程序的名称替换 HANDLER
 /subsystem=logging/console-handler=HANDLER:read-resource 

例 13.13. 显示控制台日志处理程序的配置

[standalone@localhost:9999 /] /subsystem=logging/console-handler=CONSOLE:read-resource
{
    "outcome" => "success",
    "result" => {
        "autoflush" => true,
        "encoding" => undefined,
        "filter" => undefined,
        "formatter" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n",
        "level" => "INFO",
        "target" => "System.out"
    }
}
[standalone@localhost:9999 /]
设置日志级别
请使用 change-log-level 命令和下列语法。用控制台日志处理程序的名称替换 HANDLER,并用日志级别替换 LEVEL
 /subsystem=logging/console-handler=HANDLER:change-log-level(level="LEVEL") 

例 13.14. 设置日志级别

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:change-log-level(level="TRACE")
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置目标
请使用 write-attribute 命令和下列语法。用控制台日志处理程序的名称替换 HANDLER,用分别代表标准错误流和标准输出流的 System.errSystem.out 替换 TARGET
 /subsystem=logging/console-handler=HANDLER:write-attribute(name="target", value="TARGET") 

例 13.15. 设置目标

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:write-attribute(name="target", value="System.err")
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置编码
请使用 write-attribute 命令和下列语法。用控制台日志处理程序的名称替换 HANDLER,并用所需的字符编码系统替换 ENCODING
 /subsystem=logging/console-handler=HANDLER:write-attribute(name="encoding", value="ENCODING") 

例 13.16. 设置编码

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:write-attribute(name="encoding", value="utf-8")     
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置格式器
请使用 write-attribute 命令和下列语法。用控制台日志处理程序的名称替换 HANDLER,并用格式器字符串替换 FORMAT
 /subsystem=logging/console-handler=HANDLER:write-attribute(name="formatter", value="FORMAT") 

例 13.17. 设置格式器

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:write-attribute(name="formatter", value="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n")
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置自动冲刷
请使用 write-attribute 命令和下列语法。用控制台日志处理程序的名称替换 HANDLER。如果处理程序立即写入到输出,则用 true 替换 BOOLEAN
 /subsystem=logging/console-handler=HANDLER:write-attribute(name="autoflush", value="BOOLEAN") 

例 13.18. 设置自动冲刷

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:write-attribute(name="autoflush", value="true")                                  
{"outcome" => "success"}
[standalone@localhost:9999 /]
删除控制台日志处理程序
请使用 remove 命令和下列语法。用要删除的日志处理程序的名称替换 HANDLER
 /subsystem=logging/console-handler=HANDLER:remove 

例 13.19. 删除控制台日志处理程序

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:remove
{"outcome" => "success"}
[standalone@localhost:9999 /]

13.3.4. 在 CLI 里配置文件日志处理程序

您可以在 CLI 里添加、删除和编辑文件日志处理程序。
配置文件日志处理程序的主要任务是:
  • 添加新的文件处理程序。
  • 显示文件日志处理程序的配置
  • 设置处理程序的日志级别。
  • 设置处理程序的附加行为。
  • 设置处理程序是否使用自动冲刷。
  • 设置用于处理程序输出的编码。
  • 指定日志处理程序将写入的文件。
  • 设置用于处理程序输出的格式器。
  • 删除文件日志处理程序。

重要

当在日志配置集里配置日志处理程序时,配置路径的根目录是 /subsystem=logging/logging-profile=NAME/ 而不是/subsystem=logging/
添加文件处理程序
请使用 add 命令和下列语法。用写入的日志文件的名称替换 PATH。用文件所在的目录的名称替换 DIRDIR 的值可以是一个路径变量。
 /subsystem=logging/file-handler=HANDLER:add(file={"path"=>"PATH", "relative-to"=>"DIR"}) 

例 13.20. 添加文件处理程序

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:add(file={"path"=>"accounts.log", "relative-to"=>"jboss.server.log.dir"})
{"outcome" => "success"}
[standalone@localhost:9999 /]
显示文件日志处理程序的配置
请使用 read-resource 命令和下列语法。用文件日志处理程序的名称替换 HANDLER
 /subsystem=logging/file-handler=HANDLER:read-resource 

例 13.21. 使用 read-resource 操作

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:read-resource
{
    "outcome" => "success",
    "result" => {
        "append" => true,
        "autoflush" => true,
        "encoding" => undefined,
        "file" => {
            "path" => "accounts.log",
            "relative-to" => "jboss.server.log.dir"
        },
        "filter" => undefined,
        "formatter" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n",
        "level" => undefined
    }
}
[standalone@localhost:9999 /]
设置日志级别
请使用 change-log-level 命令和下列语法。用文件日志处理程序的名称替换 HANDLER,并用日志级别替换 LEVEL
 /subsystem=logging/file-handler=HANDLER:change-log-level(level="LEVEL") 

例 13.22. 改变日志级别

/subsystem=logging/file-handler=accounts_log:change-log-level(level="DEBUG")
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置附加行为
请使用 write-attribute 命令和下列语法。用文件日志处理程序的名称替换 HANDLER。如果要求每次启动服务器时都创建新的日志文件,则用 false 替换 BOOLEAN。如果应用服务器应该继续使用相同的文件,则请用 true 替换 BOOLEAN
 /subsystem=logging/file-handler=HANDLER:write-attribute(name="append", value="BOOLEAN") 

例 13.23. 修改附加的属性

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:write-attribute(name="append", value="true")
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}
[standalone@localhost:9999 /]
重启 JBoss EAP 6 服务器以使修改生效。
设置自动冲刷
请使用 write-attribute 命令和下列语法。用文件日志处理程序的名称替换 HANDLER。如果处理程序立即写入到输出,则用 true 替换 BOOLEAN
 /subsystem=logging/file-handler=HANDLER:write-attribute(name="autoflush", value="BOOLEAN") 

例 13.24. 设置自动冲刷属性

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:write-attribute(name="autoflush", value="false")
{
    "outcome" => "success",
    "response-headers" => {"process-state" => "reload-required"}
}
[standalone@localhost:9999 /]
重启 JBoss EAP 6 服务器以使修改生效。
设置编码
请使用 write-attribute 命令和下列语法。用文件日志处理程序的名称替换 HANDLER,并用所需的字符编码系统替换 ENCODING
 /subsystem=logging/file-handler=HANDLER:write-attribute(name="encoding", value="ENCODING") 

例 13.25. 设置编码

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:write-attribute(name="encoding", value="utf-8")     
{"outcome" => "success"}
[standalone@localhost:9999 /]
指定日志处理程序将写入的文件
请使用 change-file 命令和下列语法。用写入的日志文件的名称替换 PATH。用文件所在的目录的名称替换 DIRDIR 的值可以是一个路径变量。
 /subsystem=logging/file-handler=HANDLER:change-file(file={"path"=>"PATH", "relative-to"=>"DIR"}) 

例 13.26. 指定日志处理程序将写入的文件

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:change-file(file={"path"=>"accounts-debug.log", "relative-to"=>"jboss.server.log.dir"})
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置格式器
请使用 write-attribute 命令和下列语法。用文件日志处理程序的名称替换 HANDLER,并用格式器字符串替换 FORMAT
 /subsystem=logging/file-handler=HANDLER:write-attribute(name="formatter", value="FORMAT") 

例 13.27. 设置格式器

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts-log:write-attribute(name="formatter", value="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n")
{"outcome" => "success"}
[standalone@localhost:9999 /]
删除文件日志处理程序
请使用 remove 命令和下列语法。用要删除的日志处理程序的名称替换 HANDLER
 /subsystem=logging/file-handler=HANDLER:remove 

例 13.28. 删除文件日志处理程序

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:remove
{"outcome" => "success"}
[standalone@localhost:9999 /]
日志处理程序只有没有被本地类别或异步日志处理程序引用时才可以被删除。

13.3.5. 在 CLI 里配置定期日志处理程序

您可以在 CLI 里添加、删除和编辑定期日志处理程序。
配置定期日志处理程序的主要任务是:
  • 添加新的定期日志处理程序。
  • 显示定期日志处理程序的配置
  • 设置处理程序的日志级别。
  • 设置处理程序的附加行为。
  • 设置处理程序是否使用自动冲刷。
  • 设置用于处理程序输出的编码。
  • 指定日志处理程序将写入的文件。
  • 设置用于处理程序输出的格式器。
  • 设置用于轮换日志的后缀
  • 删除定期日志处理程序。
每个任务都将在下面进行描述。

重要

当在日志配置集里配置日志处理程序时,配置路径的根目录是 /subsystem=logging/logging-profile=NAME/ 而不是/subsystem=logging/
添加新的定期轮换文件日志处理程序
使用 add 操作和下列语法。
 /subsystem=logging/periodic-rotating-file-handler=HANDLER:add(file={"path"=>"PATH", "relative-to"=>"DIR"}, suffix="SUFFIX") 
用日志文件的名称替换 HANDLER。用写入的日志文件的名称替换 PATH。用文件所在的目录的名称替换 DIRDIR 的值可以是一个路径变量。用轮换后缀替换 SUFFIX

例 13.29. 添加新的日志处理程序

[standalone@localhost:9999 /] /subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:add(file={"path"=>"daily-debug.log", "relative-to"=>"jboss.server.log.dir"}, suffix=".yyyy.MM.dd")
{"outcome" => "success"}
[standalone@localhost:9999 /]
显示定期轮换文件日志处理程序的配置
使用 read-resource 操作和下列语法。
 /subsystem=logging/periodic-rotating-file-handler=HANDLER:read-resource 
用文件日志处理程序的名称替换 HANDLER

例 13.30. 使用 read-resource 操作

[standalone@localhost:9999 /] /subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:read-resource
{
    "outcome" => "success",
    "result" => {
        "append" => true,
        "autoflush" => true,
        "encoding" => undefined,
        "file" => {
            "path" => "daily-debug.log",
            "relative-to" => "jboss.server.log.dir"
        },
        "filter" => undefined,
        "formatter" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n",
        "level" => undefined
    }
}
[standalone@localhost:9999 /]
设置日志级别
使用 change-log-level 操作和下列语法。
 /subsystem=logging/periodic-rotating-file-handler=HANDLER:change-log-level(level="LEVEL") 
用定期日志处理程序的名称替换 HANDLER,并用日志级别替换 LEVEL

例 13.31. 设置日志级别

[standalone@localhost:9999 /] /subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:change-log-level(level="DEBUG")
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置附加行为
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/periodic-rotating-handler=HANDLER:write-attribute(name="append", value="BOOLEAN") 
用定期日志处理程序的名称替换 HANDLER。如果要求每次启动服务器时都创建新的日志文件,则用 false 替换 BOOLEAN。如果应用服务器应该继续使用相同的文件,则请用 true 替换 BOOLEAN
重启 JBoss EAP 6 服务器以使修改生效。

例 13.32. 设置附加行为

[standalone@localhost:9999 /] /subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:write-attribute(name="append", value="true")
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}
[standalone@localhost:9999 /]
设置自动冲刷
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/periodic-rotating-file-handler=HANDLER:write-attribute(name="autoflush", value="BOOLEAN") 
用定期日志处理程序的名称替换 HANDLER。如果处理程序立即写入到输出,则用 true 替换 BOOLEAN
重启 JBoss EAP 6 服务器以使修改生效。

例 13.33. 设置自动冲刷行为

[standalone@localhost:9999 /] /subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:write-attribute(name="autoflush", value="false")
{
    "outcome" => "success",
    "response-headers" => {"process-state" => "reload-required"}
}
[standalone@localhost:9999 /]
设置编码
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/periodic-rotating-file-handler=HANDLER:write-attribute(name="encoding", value="ENCODING") 
用定期日志处理程序的名称替换 HANDLER,并用所需的字符编码系统替换 ENCODING

例 13.34. 设置编码

[standalone@localhost:9999 /] /subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:write-attribute(name="encoding", value="utf-8")     
{"outcome" => "success"}
[standalone@localhost:9999 /]
指定日志处理程序将写入的文件
请使用 change-file 命令和下列语法。
 /subsystem=logging/periodic-rotating-file-handler=HANDLER:change-file(file={"path"=>"PATH", "relative-to"=>"DIR"}) 
用定期文件的名称替换 HANDLER。用写入的日志文件的名称替换 PATH。用文件所在的目录的名称替换 DIRDIR 的值可以是一个路径变量。

例 13.35. 指定日志处理程序将写入的文件

[standalone@localhost:9999 /] /subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:change-file(file={"path"=>"daily-debug.log", "relative-to"=>"jboss.server.log.dir"})
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置格式器
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/periodic-rotating-file-handler=HANDLER:write-attribute(name="formatter", value="FORMAT") 
用定期日志处理程序的名称替换 HANDLER,并用格式器字符串替换 FORMAT

例 13.36. 设置格式器

[standalone@localhost:9999 /] /subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:write-attribute(name="formatter", value="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n")
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置用于轮换日志的后缀
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/periodic-rotating-file-handler=HANDLER:write-attribute(name="suffix", value="SUFFIX") 
用日志处理程序的名称替换 HANDLER,并用所需的后缀替换 SUFFIX

例 13.37. 

[standalone@localhost:9999 /] /subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:write-attribute(name="suffix", value=".yyyy-MM-dd-HH")
{"outcome" => "success"}
[standalone@localhost:9999 /]
删除定期日志处理程序
使用 remove 操作和下列语法。
 /subsystem=logging/periodic-rotating-file-handler=HANDLER:remove 
用定期日志处理程序的名称替换 HANDLER

例 13.38. 删除定期日志处理程序

[standalone@localhost:9999 /] /subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:remove
{"outcome" => "success"}
[standalone@localhost:9999 /]

13.3.6. 在 CLI 里配置 Size 日志处理程序

您可以在 CLI 里添加、删除和编辑 Size 轮换文件日志处理程序。
配置 Size 日志处理程序的主要任务是:
  • 添加新的日志处理程序。
  • 显示日志处理程序的配置
  • 设置处理程序的日志级别。
  • 设置处理程序的附加行为。
  • 设置处理程序是否使用自动冲刷。
  • 设置用于处理程序输出的编码。
  • 指定日志处理程序将写入的文件。
  • 设置用于处理程序输出的格式器。
  • 设置每个日志文件的最大尺寸。
  • 设置要保持的备份日志的最大数目。
  • 删除日志处理程序。
每个任务都将在下面进行描述。

重要

当在日志配置集里配置日志处理程序时,配置路径的根目录是 /subsystem=logging/logging-profile=NAME/ 而不是/subsystem=logging/
添加新的日志处理程序。
使用 add 操作和下列语法。
 /subsystem=logging/size-rotating-file-handler=HANDLER:add(file={"path"=>"PATH", "relative-to"=>"DIR"}) 
用日志文件的名称替换 HANDLER。用写入的日志文件的名称替换 PATH。用文件所在的目录的名称替换 DIRDIR 的值可以是一个路径变量。

例 13.39. 添加新的日志处理程序。

[standalone@localhost:9999 /] /subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:add(file={"path"=>"accounts_trace.log", "relative-to"=>"jboss.server.log.dir"}) 
{"outcome" => "success"}
[standalone@localhost:9999 /]
显示日志处理程序的配置
使用 read-resource 操作和下列语法。
 /subsystem=logging/size-rotating-file-handler=HANDLER:read-resource 
用文件日志处理程序的名称替换 HANDLER

例 13.40. 显示日志处理程序的配置

[standalone@localhost:9999 /] /subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:read-resource
{
    "outcome" => "success",
    "result" => {
        "append" => true,
        "autoflush" => true,
        "encoding" => undefined,
        "file" => {
            "path" => "accounts_trace.log",
            "relative-to" => "jboss.server.log.dir"
        },
        "filter" => undefined,
        "formatter" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n",
        "level" => undefined,
        "max-backup-index" => 1,
        "rotate-size" => "2m"
    }
}
[standalone@localhost:9999 /]
设置处理程序的日志级别
使用 change-log-level 操作和下列语法。
 /subsystem=logging/size-rotating-file-handler=HANDLER:change-log-level(level="LEVEL") 
用文件日志处理程序的名称替换 HANDLER,并用日志级别替换 LEVEL

例 13.41. 设置处理程序的日志级别

[standalone@localhost:9999 /] /subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:change-log-level(level="TRACE")
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置处理程序的附加行为。
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/size-rotating-file-handler=HANDLER:write-attribute(name="append", value="BOOLEAN") 
用文件日志处理程序的名称替换 HANDLER。如果要求每次启动服务器时都创建新的日志文件,则用 false 替换 BOOLEAN。如果应用服务器应该继续使用相同的文件,则请用 true 替换 BOOLEAN
重启 JBoss EAP 6 服务器以使修改生效。

例 13.42. 设置处理程序的附加行为。

[standalone@localhost:9999 /] /subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:write-attribute(name="append", value="true")
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}
[standalone@localhost:9999 /]
设置处理程序是否使用自动冲刷。
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/size-rotating-file-handler=HANDLER:write-attribute(name="autoflush", value="BOOLEAN") 
用文件日志处理程序的名称替换 HANDLER。如果处理程序立即写入到输出,则用 true 替换 BOOLEAN

例 13.43. 设置处理程序是否使用自动冲刷。

[standalone@localhost:9999 /] /subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:write-attribute(name="autoflush", value="true")
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置用于处理程序输出的编码。
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/size-rotating-file-handler=HANDLER:write-attribute(name="encoding", value="ENCODING") 
用文件日志处理程序的名称替换 HANDLER,并用所需的字符编码系统替换 ENCODING

例 13.44. 设置用于处理程序输出的编码。

[standalone@localhost:9999 /] /subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:write-attribute(name="encoding", value="utf-8") 
{"outcome" => "success"}
[standalone@localhost:9999 /]
指定日志处理程序将写入的文件。
请使用 change-file 命令和下列语法。
 /subsystem=logging/size-rotating-file-handler=HANDLER:change-file(file={"path"=>"PATH", "relative-to"=>"DIR"}) 
用日志文件的名称替换 HANDLER。用写入的日志文件的名称替换 PATH。用文件所在的目录的名称替换 DIRDIR 的值可以是一个路径变量。

例 13.45. 指定日志处理程序将写入的文件。

[standalone@localhost:9999 /] /subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:change-file(file={"path"=>"accounts_trace.log", "relative-to"=>"jboss.server.log.dir"}) 
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置用于处理程序输出的格式器。
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/size-rotating-file-handler=HANDLER:write-attribute(name="formatter", value="FORMATTER") 
用文件日志处理程序的名称替换 HANDLER,并用格式器字符串替换 FORMAT

例 13.46. 设置用于处理程序输出的格式器。

[standalone@localhost:9999 /] /subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:write-attribute(name="formatter", value="%d{HH:mm:ss,SSS} %-5p (%c) [%t] %s%E%n")
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置每个日志文件的最大尺寸。
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/size-rotating-file-handler=HANDLER:write-attribute(name="rotate-size", value="SIZE") 
用文件日志处理程序的名称替换 HANDLER,并用文件大小的最大值替换 SIZE

例 13.47. 设置每个日志文件的最大尺寸。

[standalone@localhost:9999 /] /subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:write-attribute(name="rotate-size", value="50m")  
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置要保持的备份日志的最大数目。
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/size-rotating-file-handler=HANDLER:write-attribute(name="max-backup-index", value="NUMBER") 
用文件日志处理程序的名称替换 HANDLER,并用要保留的日志文件的数目替换 NUMBER

例 13.48. 设置要保持的备份日志的最大数目。

[standalone@localhost:9999 /] /subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:write-attribute(name="max-backup-index", value="5")
{"outcome" => "success"}
[standalone@localhost:9999 /]
删除日志处理程序
使用 remove 操作和下列语法。
 /subsystem=logging/size-rotating-file-handler=HANDLER:remove 
用文件日志处理程序的名称替换 HANDLER

例 13.49. 删除日志处理程序

[standalone@localhost:9999 /] /subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:remove
{"outcome" => "success"}
[standalone@localhost:9999 /]

13.3.7. 在 CLI 里配置异步日志处理程序

您可以在 CLI 里添加、删除和编辑异步(Async)日志处理程序。
配置异步日志处理程序的主要任务是:
  • 添加新的异步日志处理程序。
  • 显示异步日志处理程序的配置
  • 改变日志级别
  • 设置队列长度
  • 设置溢出动作
  • 添加子处理程序
  • 删除子处理程序
  • 删除异步日志处理程序
每个任务都将在下面进行描述。

重要

当在日志配置集里配置日志处理程序时,配置路径的根目录是 /subsystem=logging/logging-profile=NAME/ 而不是/subsystem=logging/
添加新的异步日志处理程序。
使用 add 操作和下列语法。
 /subsystem=logging/async-handler=HANDLER:add(queue-length="LENGTH") 
用文件日志处理程序的名称替换 HANDLER,并用保持在队列里的日志请求的最大数目替换 LENGTH

例 13.50. 

[standalone@localhost:9999 /] /subsystem=logging/async-handler=NFS_LOGS:add(queue-length="10")
{"outcome" => "success"}
[standalone@localhost:9999 /]
显示异步日志处理程序的配置
使用 read-resource 操作和下列语法。
 /subsystem=logging/async-handler=HANDLER:read-resource 
用文件日志处理程序的名称替换 HANDLER

例 13.51. 

[standalone@localhost:9999 /] /subsystem=logging/async-handler=NFS_LOGS:read-resource
{
    "outcome" => "success",
    "result" => {
        "encoding" => undefined,
        "filter" => undefined,
        "formatter" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n",
        "level" => undefined,
        "overflow-action" => "BLOCK",
        "queue-length" => "50",
        "subhandlers" => undefined
    }
}
[standalone@localhost:9999 /]
改变日志级别
使用 change-log-level 操作和下列语法。
 /subsystem=logging/async-handler=HANDLER:change-log-level(level="LEVEL") 
用文件日志处理程序的名称替换 HANDLER,并用日志级别替换 LEVEL

例 13.52. 

[standalone@localhost:9999 /] /subsystem=logging/async-handler=NFS_LOGS:change-log-level(level="INFO")
{"outcome" => "success"}
[standalone@localhost:9999 /]
设置队列长度
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/async-handler=HANDLER:write-attribute(name="queue-length", value="LENGTH") 
用文件日志处理程序的名称替换 HANDLER,并用保持在队列里的日志请求的最大数目替换 LENGTH
重启 JBoss EAP 6 服务器以使修改生效。

例 13.53. 

[standalone@localhost:9999 /] /subsystem=logging/async-handler=NFS_LOGS:write-attribute(name="queue-length", value="150")
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}
[standalone@localhost:9999 /]
设置溢出动作
请使用 write-attribute 命令和下列语法。
 /subsystem=logging/async-handler=HANDLER:write-attribute(name="overflow-action", value="ACTION") 
用文件日志处理程序的名称替换 HANDLER,并用 DISCARDBLOCK 替换 ACTION

例 13.54. 

[standalone@localhost:9999 /] /subsystem=logging/async-handler=NFS_LOGS:write-attribute(name="overflow-action", value="DISCARD")
{"outcome" => "success"}
[standalone@localhost:9999 /]
添加子处理程序
请使用 assign-subhandler 命令和下列语法。
 /subsystem=logging/async-handler=HANDLER:assign-subhandler(name="SUBHANDLER") 
用文件日志处理程序的名称替换 HANDLER,并用将被添加为子处理程序的日志处理程序的名称替换 SUBHANDLER

例 13.55. 

[standalone@localhost:9999 /] /subsystem=logging/async-handler=NFS_LOGS:assign-subhandler(name="NFS_FILE")       
{"outcome" => "success"}
[standalone@localhost:9999 /]
删除子处理程序
请使用 unassign-subhandler 命令和下列语法。
 /subsystem=logging/async-handler=HANDLER:unassign-subhandler(name="SUBHANDLER") 
用文件日志处理程序的名称替换 HANDLER,并用要删除的子处理程序的名称替换 SUBHANDLER

例 13.56. 

[standalone@localhost:9999 /] /subsystem=logging/async-handler=NFS_LOGS:unassign-subhandler(name="NFS_FILE")       
{"outcome" => "success"}
[standalone@localhost:9999 /]
删除异步日志处理程序
使用 remove 操作和下列语法。
 /subsystem=logging/async-handler=HANDLER:remove 
用文件日志处理程序的名称替换 HANDLER

例 13.57. 

[standalone@localhost:9999 /] /subsystem=logging/async-handler=NFS_LOGS:remove       
{"outcome" => "success"}
[standalone@localhost:9999 /]

13.3.8. 配置 syslog 处理程序

JBoss EAP 6 的 lognamager 现在包含一个 Syslog 处理程序。Syslog 处理程序用于发送消息到远程日志服务器。它允许多个应用程序发送它们的日志消息到相同的服务器,一起进行解析。本节介绍如何通过管理 CLI 和可用的配置选项创建和配置处理程序。
  • 管理 CLI 的访问权限

过程 13.1. 添加 syslog 处理程序

  • 运行下列命令来添加 syslog 处理程序
    /subsystem=logging/syslog-handler=HANDLER_NAME:add

过程 13.2. 配置 syslog 处理程序

  • 运行下列命令来配置 syslog 处理程序属性:
    /subsystem=logging/syslog-handler=HANDLER_NAME:write-attribute(name=ATTRIBUTE_NAME,value=ATTRIBUTE_VALUE)

过程 13.3. 删除 syslog 处理程序

  • 运行以下命令删除现有的 Syslog 处理程序:
    /subsystem=logging/syslog-handler=HANDLER_NAME:remove
Expand
表 13.6. 表标题
属性 描述 默认值
port Syslog 服务器侦听的端口。 514
app-name 以 RFC5424 格式化消息时使用的 App 名称。 null
enabled 如果设置为 true,启用处理程序。如果设置为 false,处理日志消息时将忽略处理程序。 true
级别 指定哪些消息将被记录的日志级别。低于这个级别的消息将被忽略。 ALL
facility 依照 RFC-5424 所 RFC-3164 定义的 user-level
server-address Syslog 服务器的地址 localhost
hostname 发送消息的主机的名称。 null
syslog-format 按照 RFC 规格格式化日志消息 RFC5424
name 处理程序的名称 null

13.4. 日志配置集

13.4.1. 关于日志配置集

重要

日志配置集(Logging Profile)适用于版本 6.1.0 和之后的版本
日志配置集(Logging Profile)是独立的日志配置,它可以分配到部署的应用程序上。日志配置集可以定义处理程序、类别和 Root Logger,就像普通的日志子系统。但它不能在其他配置集或主日志子系统里引用配置。日志配置集的设计简便了日志子系统的配置。
日志配置集允许管理员为一个或多个应用程序创建日志配置,而不会影响到其他的日志配置。因为每个配置集都定义在服务器配置里,这意味着您可以修改日志配置而无需重部署受影响的应用程序。
每个日志配置集都有下列配置:
  • 唯一名称。这是必需的配置。
  • 任意数量的日志处理程序。
  • 任意数量的日志类别。
  • 最多一个 Root Logger。
应用程序可以用 Logging-profile 属性指定一个日志配置集来使用它的 MANIFEST.MF 文件。

重要

无法用管理控制台配置日志配置集。

13.4.2. 用 CLI 创建新的日志配置集

您可以用下面的 CLI 命令创建新的日志配置集,请用自己的配置集名替换 NAME
/subsystem=logging/logging-profile=NAME:add
这将创建一个可以添加处理程序、类别和 Root Logger 的新的空配置集。

13.4.3. 用 CLI 配置日志配置集

日志配置集可以用和配置主日志子系统几乎相同的语法来配置日志处理程序、类别和 Root Logger。
配置日志子系统和日志配置集只有两个不同之处:
  1. 根配置路径是 /subsystem=logging/logging-profile=NAME
  2. 日志配置集不能包含其他日志配置集。
请参考合适的日志管理任务:

例 13.58. 创建和配置日志配置集

创建日志配置集并添加一个类别和文件日志处理程序。
  1. 创建配置集:
    /subsystem=logging/logging-profile=accounts-app-profile:add
  2. 创建文件处理程序
    /subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:add(file={path=>"ejb-trace.log", "relative-to"=>"jboss.server.log.dir"})
    /subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:change-log-level(level="DEBUG")
  3. 创建日志类别
    /subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:add(level=TRACE)
  4. 分配文件处理程序给类别
    /subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:assign-handler(name="ejb-trace-file")

13.4.4. 指定应用程序里的日志配置集

应用程序在 MANIFEST.MF 文件里指定要使用的日志配置集。

预备条件:

  1. 您必须知道服务器上为这个应用程序设置的日志配置集的名称,您可以咨询服务器管理员要使用的配置集名称。

过程 13.4. 添加日志配置集到应用程序里

  • 编辑 MANIFEST.MF

    如果您的应用程序没有 MANIFEST.MF 文件:用下列内容创建一个,用配置集名替换NAME
    Manifest-Version: 1.0
          Logging-Profile: NAME
    
    如果您的应用程序已经有了 MANIFEST.MF 文件:添加下列行,用配置集名替换NAME
    Logging-Profile: NAME
    

注意

如果您在使用 Maven 和 maven-war-plugin,您可以将 MANIFEST.MF 文件置于 src/main/resources/META-INF/ 并添加下列配置到 pom.xml 文件里。
<plugin>
      <artifactId>maven-war-plugin</artifactId>
      <configuration>
        <archive>
          <manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile>  
        </archive>
      </configuration>
   </plugin>
当应用程序被部署时,它会对日志消息使用指定日志配置集里的配置。

13.4.5. 日志配置集配置示例

这个例子展示了日志配置集的配置以及使用它的应用程序。它也展示了 CLI 会话、生成的 XML 配置以及应用程序的 MANIFEST.MF 文件。
这个日志配置集示例具有下列特点:
  • 名称是 accounts-app-profile
  • 日志类别是 com.company.accounts.ejbs
  • 日志级别是 TRACE
  • 日志处理程序是使用 ejb-trace.log 的文件处理程序。

例 13.59. CLI 会话

localhost:bin user$ ./jboss-cli.sh -c
[standalone@localhost:9999 /] /subsystem=logging/logging-profile=accounts-app-profile:add
{"outcome" => "success"}

[standalone@localhost:9999 /] /subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:add(file={path=>"ejb-trace.log", "relative-to"=>"jboss.server.log.dir"})
{"outcome" => "success"}

[standalone@localhost:9999 /] /subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:change-log-level(level="DEBUG")
{"outcome" => "success"}

[standalone@localhost:9999 /] /subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:add(level=TRACE)
{"outcome" => "success"}

[standalone@localhost:9999 /] /subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:assign-handler(name="ejb-trace-file")
{"outcome" => "success"}

[standalone@localhost:9999 /]

例 13.60. XML 配置

<logging-profiles>
   <logging-profile name="accounts-app-profile">
      <file-handler name="ejb-trace-file">
         <level name="DEBUG"/>
         <file relative-to="jboss.server.log.dir" path="ejb-trace.log"/>
      </file-handler>
      <logger category="com.company.accounts.ejbs">
         <level name="TRACE"/>
         <handlers>
            <handler name="ejb-trace-file"/>
         </handlers>
      </logger>
   </logging-profile>
</logging-profiles>

例 13.61. 应用程序的 MANIFEST.MF 文件

Manifest-Version: 1.0
Logging-Profile: accounts-app-profile

13.5. 日志配置属性

13.5.1. Root Logger 属性

Expand
表 13.7. Root Logger 属性
属性 数据类型 描述
level String
root logger 记录的最大级别的日志消息。
handlers String[]
Root Logger 使用的处理程序列表。
filter-spec String
定义过滤器的表达式,下面的表达式定义了一个过滤器,它排除某个模式:not(match("JBAS.*"))

13.5.2. 日志类别属性

Expand
表 13.8. 日志类别属性
属性 数据类型 描述
级别 String
日志类别记录的最大级别的日志消息。
handlers String[]
Root Logger 使用的处理程序列表。
use-parent-handlers Boolean
如果为 true,除了其他分配的处理程序外,这个列表将使用 Root Logger 日志处理程序。
category String
哪个日志类别里的消息将被记录。
filter-spec String
定义过滤器的表达式,下面的表达式定义了一个过滤器,它排除某个模式:not(match("JBAS.*"))

13.5.3. Console Log Handler 的属性

Expand
表 13.9. Console Log Handler 的属性
属性 数据类型 描述
level String
日志处理程序记录的最大级别的日志消息。
encoding String
输出所使用的编码模式。
formatter String
这个日志处理程序使用的日志格式器。
target String
日志处理程序的输出所去往的系统输出流,这可以是系统错误流的 System.err 或标准输出流的 System.out。
autoflush Boolean
如果为 true,日志消息在接收后将立即被送往处理程序目标。
name String
这个日志处理程序的唯一标识。
enabled Boolean
如果设置为 true,启用处理程序。如果设置为 false,处理日志消息时将忽略处理程序。
filter-spec String
定义过滤器的表达式,下面的表达式定义了一个过滤器,它排除某个模式:not(match("JBAS.*"))

13.5.4. 文件处理程序属性

Expand
表 13.10. 文件处理程序属性
属性 数据类型 描述
level String
日志处理程序记录的最大级别的日志消息。
encoding String
输出所使用的编码模式。
formatter String
这个日志处理程序使用的日志格式器。
append Boolean
如果为 true,这个处理程序写入的所有日志消息将附加在文件(如果已经存在)后面。如果为 false,每次应用程序启动时都会创建一个新的文件。对 append 的修改要求服务器重启以使其生效。
autoflush Boolean
如果为 true,日志消息在接收后将立即被送往处理程序。对 autoflush 的修改要求服务器重启以使其生效。
名称 String
这个日志处理程序的唯一标识。
file Object
这个对象代表了日志处理程序输出写入的文件。它有两个配置属性:relative-topath
relative-to String
这是文件对象的属性,也是日志文件写入的目录。在这里可以指定 JBoss EAP 6 的文件路径变量。jboss.server.log.dir 变量指向服务器的 log/
path String
这是文件对象的属性,也是日志消息写入的文件。它是附加在 relative-to 属性上以确定完整路径的相对路径名。
enabled Boolean
如果设置为 true,启用处理程序。如果设置为 false,处理日志消息时将忽略处理程序。
filter-spec String
定义过滤器的表达式,下面的表达式定义了一个过滤器,它排除某个模式:not(match("JBAS.*"))

13.5.5. 定期日志处理程序属性

Expand
表 13.11. 定期日志处理程序属性
属性 数据类型 描述
append Boolean
如果为 true,这个处理程序写入的所有日志消息将附加在文件(如果已经存在)后面。如果为 false,每次应用程序启动时都会创建一个新的文件。对 append 属性的修改要求服务器重启以使其生效。
autoflush Boolean
如果为 true,日志消息在接收后将立即被送往处理程序。对 autoflush 的修改要求服务器重启以使其生效。
encoding String
输出所使用的编码模式。
formatter String
这个日志处理程序使用的日志格式器。
级别 String
日志处理程序记录的最大级别的日志消息。
名称 String
这个日志处理程序的唯一标识。
文件 Object
这个对象代表了日志处理程序输出写入的文件。它有两个配置属性:relative-topath
relative-to String
这是文件对象的属性,也是日志文件写入的目录。在这里可以指定 JBoss EAP 6 的文件路径变量。jboss.server.log.dir 变量指向服务器的 log/
path String
这是文件对象的属性,也是日志消息写入的文件。它是附加在 relative-to 属性上以确定完整路径的相对路径名。
suffix String
这个字符串附加在轮换日志文件的名称后面,用于确定轮换的频率。后缀的格式是 (.) 加上 java.text.SimpleDateFormat 类解析的日期字符串。日志文件根据后缀定义的最小时间单元进行轮换。例如,后缀 .yyyy-MM-dd 将每日进行轮换。
enabled Boolean
如果设置为 true,启用处理程序。如果设置为 false,处理日志消息时将忽略处理程序。
filter-spec String
定义过滤器的表达式,下面的表达式定义了一个过滤器,它排除某个模式:not(match("JBAS.*"))

13.5.6. 大小日志处理程序属性

Expand
表 13.12. 大小日志处理程序属性
属性 数据类型 描述
append Boolean
如果为 true,这个处理程序写入的所有日志消息将附加在文件(如果已经存在)后面。如果为 false,每次应用程序启动时都会创建一个新的文件。对 append 属性的修改要求服务器重启以使其生效。
autoflush Boolean
如果为 true,日志消息在接收后将立即被送往处理程序。对 append 属性的修改要求服务器重启以使其生效。
encoding String
输出所使用的编码模式。
formatter String
这个日志处理程序使用的日志格式器。
级别 String
日志处理程序记录的最大级别的日志消息。
名称 String
这个日志处理程序的唯一标识。
file Object
这个对象代表了日志处理程序输出写入的文件。它有两个配置属性:relative-topath
relative-to String
这是文件对象的属性,也是日志文件写入的目录。在这里可以指定 JBoss EAP 6 的文件路径变量。jboss.server.log.dir 变量指向服务器的 log/
path String
这是文件对象的属性,也是日志消息写入的文件。它是附加在 relative-to 属性上以确定完整路径的相对路径名。
rotate-size Integer
在日志文件轮换前可到达的最大尺寸。数字后面的单个字符表示单位:b 表示字节、 k 表示千字节、m 表示兆字节\g 表示千兆字节、50m 表示 50 兆字节。
max-backup-index Integer
设置要保持的轮换日志的最大数目。到达这个数目时,最旧的日志将被重用。
enabled Boolean
如果设置为 true,启用处理程序。如果设置为 false,处理日志消息时将忽略处理程序。
filter-spec String
定义过滤器的表达式,下面的表达式定义了一个过滤器,它排除某个模式:not(match("JBAS.*"))
rotate-on-boot Boolean
如果为 true,服务器重启时将创建新的日志文件。默认值是 false

13.5.7. 异步日志处理程序属性

Expand
表 13.13. 异步日志处理程序属性
属性 数据类型 描述
level String
日志处理程序记录的最大级别的日志消息。
name String
这个日志处理程序的唯一标识。
queue-length Integer
在等待子处理程序响应时这个处理程序保留的日志消息的最大数目。
overflow-action String
当超过队列长度时,这个处理程序如何响应。它可以设置为 BLOCKDISCARDBLOCK 让日志应用程序等待,直至队列里出现可用的空间。这和非异步日志处理程序有着相同的行为。DISCARD 则允许日志应用程序继续,但会删除日志消息。
subhandlers String[]
这个异步处理程序传入日志消息的处理程序的列表。
enabled Boolean
如果设置为 true,启用处理程序。如果设置为 false,处理日志消息时将忽略处理程序。
filter-spec String
定义过滤器的表达式,下面的表达式定义了一个过滤器,它排除某个模式:not(match("JBAS.*"))

13.6. 用于日志的 XML 配置示例

13.6.1. 用于 Root Logger 的 XML 配置示例

<subsystem xmlns="urn:jboss:domain:logging:1.2">

   <root-logger>
      <level name="INFO"/>
      <handlers>
         <handler name="CONSOLE"/>
         <handler name="FILE"/>
      </handlers>
   </root-logger>

</subsystem>

13.6.2. 用于日志类别的 XML 配置示例

<subsystem xmlns="urn:jboss:domain:logging:1.2">

   <logger category="com.company.accounts.rec">
      <handlers>
         <handler name="accounts-rec"/>
      </handlers>
   </logger>

</subsystem>

13.6.3. 用于 Console Log Handler 的 XML 配置示例

<subsystem xmlns="urn:jboss:domain:logging:1.2">

   <console-handler name="CONSOLE">
      <level name="INFO"/>
      <formatter>
         <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
      </formatter>
   </console-handler>

</subsystem>

13.6.4. 用于 File Log Handler 的 XML 配置示例

<file-handler name="accounts-rec-trail" autoflush="true">
    <level name="INFO"/>
    <file relative-to="jboss.server.log.dir" path="accounts-rec-trail.log"/>
    <append value="true"/>
</file-handler>

13.6.5. 用于 Periodic Log Handler 的 XML 配置示例

<periodic-rotating-file-handler name="FILE">
   <formatter>
      <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
   </formatter>
   <file relative-to="jboss.server.log.dir" path="server.log"/>
   <suffix value=".yyyy-MM-dd"/>
   <append value="true"/>
</periodic-rotating-file-handler>

13.6.6. 用于 Size Log Handler 的 XML 配置示例

<size-rotating-file-handler name="accounts_debug" autoflush="false">
   <level name="DEBUG"/>
   <file relative-to="jboss.server.log.dir" path="accounts-debug.log"/>
   <rotate-size value="500k"/>
   <max-backup-index value="5"/>
   <append value="true"/>
</size-rotating-file-handler>

13.6.7. 用于 Async Log Handler 的 XML 配置示例

<async-handler name="Async_NFS_handlers">
   <level name="INFO"/>
   <queue-length value="512"/>
   <overflow-action value="block"/>
   <subhandlers>
      <handler name="FILE"/>
      <handler name="accounts-record"/>
   </subhandlers>
</async-handler>

第 14 章 JVM

14.1. 关于 JVM

14.1.1. 关于 JVM 设置

对于受管域和独立服务器实例,Java 虚拟机(JVM)设置是不同的。在受管域里,JVM 设置是在 host.xmldomain.xml 配置文件里声明的,由负责启动和停止服务器进程的域控制器组件确定。而在独立服务器实例里,服务器的启动过程可以传入命令行参数。这可以通过命令行或管理控制台的 System Properties 屏幕里进行声明。
受管域

受管域的一个重要特征是可以定义多级别的 JVM 设置。您可以在主机、服务器组、服务器实例级别配置定义 JVM 设置。您可以用更专用的子元素覆盖父配置,这允许声明专有的服务器配置而无需在组或主机级别进行排除。这也允许其他级别继承父配置,直至在运行时传入或在配置文件里声明设置。

例 14.1. 域配置文件里的 JVM 设置

下面的例子展示了 domain.xml 配置文件里的服务器组的 JVM 声明。
<server-groups>
       <server-group name="main-server-group" profile="default">
           <jvm name="default">
               <heap size="64m" max-size="512m"/>
           </jvm>
           <socket-binding-group ref="standard-sockets"/>
       </server-group>
       <server-group name="other-server-group" profile="default">
           <jvm name="default">
               <heap size="64m" max-size="512m"/>
           </jvm>
           <socket-binding-group ref="standard-sockets"/>
       </server-group>
</server-groups>

在这个例子里,名为 main-server-group 的组声明了大小为 64MB 的堆,其最大堆大小为 512MB。属于这个组的任何服务器都将继承这些设置。你可以为整个组、为某个主机、或者单个服务器修改这些设置。

例 14.2. 主机配置文件里的域设置

下面的例子展示了 host.xml 配置文件里的服务器组的 JVM 声明。
<servers>
       <server name="server-one" group="main-server-group" auto-start="true">
           <jvm name="default"/>
       </server>
       <server name="server-two" group="main-server-group" auto-start="true">
           <jvm name="default">
               <heap size="64m" max-size="256m"/>
           </jvm>
           <socket-binding-group ref="standard-sockets" port-offset="150"/>
       </server>
       <server name="server-three" group="other-server-group" auto-start="false">
           <socket-binding-group ref="standard-sockets" port-offset="250"/>
       </server>
</servers>

在这个例子里,名为 server-two 的服务器属于 main-server-group 服务器组,它继承了 default JVM 组的设置。在前面的例子里,main-server-group 的主要堆大小是 512MB。通过声明更小的最大堆尺寸为 256MB,server-two 可以覆盖 domain.xml 设置来按需要调整性能。
运行时的独立服务器设置

独立服务器实例的 JVM 设置可以在启动服务器前通过设置 JAVA_OPTS 环境变量来声明。下面是在 Linux 命令行里设置 JAVA_OPTS 环境变量的例子:

[user@host bin]$ export JAVA_OPTS="-Xmx1024M"
相同的设置可以用于 Microsoft Windows 环境,如:
C:\> set JAVA_OPTS="Xmx1024M"
或者,可以将 JVM 设置添加到 EAP_HOME/bin 目录下的 standalone.conf 文件里,它包含了传入 JVM 的选项示例。

14.1.2. 在管理控制台里显示 JVM 状态

独立服务器或受管域的 Java 虚拟机(Java Virtual Machine,JVM)状态都可以在管理控制台里显示。控制台以 MB 单位显示了堆、线程的使用情况。虽然统计数据并非实时显示的,但您可以刷新控制台来显示 JVM 资源的最新状况。
JVM 状态包含下列数值。
Expand
表 14.1. JVM 状态属性
类型 描述
Max 用于内存管理的最大内存数量(字节)。
Used 已使用的内存数量(MB)。
Committed 提交给 JVM 使用的内存数量(字节)。
Init JVM 从操作系统请求的用于内存管理的初始内存数量(字节)。

过程 14.1. 在管理控制台里显示 JVM 状态

  • 显示 JVM 状态

    您可以查看独立服务器或受管域的 JVM 状态。
    • 显示独立服务器实例的 JVM 状态

      Runtime 屏幕的 Server Status 菜单里选择 JVM Status
    • 显示受管域的 JVM 状态

      在 Runtime 屏幕的 Domain Status 菜单里选择 JVM Status。
    • 受管域可以提供服务器组里的所有服务器实例的可视性,但它只允许您在服务器菜单里一次查看一个服务器。要查看服务器组里其他服务器的状态,请点击屏幕左上角的下拉框,选择要查看的主机和服务器,然后点击 Done 加载结果。
结果

显示服务器实例的 JVM 设置的状态。

第 15 章 Web 子系统

15.1. 配置 Web 子系统

您可以用基于 Web 的管理控制台或命令行管理 CLI 配置 Web 子系统的大多数方面。我们会按管理控制台里出现的顺序逐一解释每个设置,同时也提供对管理 CLI 命令的解释。
用管理控制台查看 Web 子系统

要使用基于 Web 的管理控制台配置 Web 子系统,请点击右上角的 Profile(s) 标签页。对于受管域,从左上角的 Profile(s) 里选择您要配置的服务器配置集。展开 Subsystems 菜单,然后展开 Web 菜单。屏幕会显示 Web 子系统的每个可配置部分。

注意

对于受管域,只有您的配置集是 hafull-ha 时,或者如果您用 standalone-hastandalone-full-ha 配置集启动独立服务器时,mod_cluster 组件才可用;mod_cluster 配置的详情请参考 第 16.5.2 节 “配置 mod_cluster 子系统”
配置 JSP 容器、HTTP 连接器和虚拟 HTTP 服务器

要配置 JSP 容器、HTTP 连接器和虚拟 HTTP 服务器,请点击 Servlet/HTTP 菜单条目。点击 Edit 按钮修改任何值。点击 Advanced 按钮查看高级选项。下面解释了这些选项。HTTP 连接器和虚拟服务器的选项显示在单独的表里。

Expand
表 15.1. Servlet/HTTP 配置选项
选项 描述 CLI 命令
Disabled?
如果为 true,禁用 JSP 容器。默认是 false。如果您没有使用任何 JSP,这会很有用。
/profile=full-ha/subsystem=web/configuration=jsp-configuration/:write-attribute(name=disabled,value=false)
Development?
如果为 true,则启用 Development Mode,这会产生更多冗余的调试信息。默认是 false
/profile=full-ha/subsystem=web/configuration=jsp-configuration/:write-attribute(name=development,value=false)
Keep Generated?
如果这个选项是隐藏的,点击 Advanced 查看这个选项。如果为 true 则保持生成的 Servlets。它默认是启用的。
/profile=full-ha/subsystem=web/configuration=jsp-configuration/:write-attribute(name=keep-generated,value=true)
Check Interval?
如果这个选项是隐藏的,点击 Advanced 查看这个选项。这个值以秒为单位,它确定用后台进程检查 JSP 更新的频率。默认值是 0
/profile=full-ha/subsystem=web/configuration=jsp-configuration/:write-attribute(name=check-interval,value=0)
Display Source?
如果这个选项是隐藏的,点击 Advanced 查看这个选项。如果为 true,当 runtime 错误发生时会显示 JSP 源码片段。默认值是 true
/profile=full-ha/subsystem=web/configuration=jsp-configuration/:write-attribute(name=display-source-fragment,value=true)
对于负载平衡和 HA 群集,AJP 和 HTTP 连接器使用 mod_clustermod_jkmod_proxyISAPINSAPI。要配置连接器,请选择 Connectors 标签并点击 Add。要删除连接器,请选中这个条目并点击 Remove。要编辑连接器,选中后点击 Edit
如下列命令所示,当您用管理 CLI 创建新的连接器时,可以立即设置所需选项。

例 15.1. 创建新的连接器

/profile=full-ha/subsystem=web/connector=ajp/:add(socket-binding=ajp,scheme=http,protocol=AJP/1.3,secure=false,name=ajp,max-post-size=2097152,enabled=true,enable-lookups=false,redirect-port=8433,max-save-post-size=4096)
Expand
表 15.2. 连接器选项
选项 描述 CLI 命令
Name
连接器的唯一名称,用于显示目的。
/profile=full-ha/subsystem=web/connector=ajp/:read-attribute(name=name)
Socket Binding
连接器应该绑定的命名套接字绑定。套接字绑定是套接字名称和网络端口之间的映射。套接字绑定是对每个独立服务器配置的,对于受管域则通过套接字绑定组进行配置。套接字绑定组应用于服务器组。
/profile=full-ha/subsystem=web/connector=ajp/:write-attribute(name=socket-binding,value=ajp)
Scheme
Web 连接器 scheme,如 HTTP 或 HTTPS。
/profile=full-ha/subsystem=web/connector=ajp/:write-attribute(name=scheme,value=http)
Protocol
要使用的 Web 连接器协议,如 AJP 或 HTTP。
/profile=full-ha/subsystem=web/connector=ajp/:write-attribute(name=protocol,value=AJP/1.3)
Enabled
是否启用这个 Web 连接器。
/profile=full-ha/subsystem=web/connector=ajp/:write-attribute(name=enabled,value=true)
要配置虚拟服务器,请点击 Virtual Servers 标签页。请用 Add 按钮来添加新的虚拟服务器。要编辑或删除虚拟服务器,选中相关条目并点击 EditRemove 按钮。
如下列命令所示,当您用管理 CLI 添加新的虚拟服务器时,可以立即设置所需选项。

例 15.2. 添加新的虚拟服务器

/profile=full-ha/subsystem=web/virtual-server=default-host/:add(enable-welcome-root=true,default-web-module=ROOT.war,alias=["localhost","example.com"],name=default-host)
Expand
表 15.3. 虚拟服务器选项
选项 描述 CLI 命令
Name
虚拟服务器的唯一名称,用于显示目的。
Alias
应该匹配这个虚拟服务器的主机名的列表。在管理控制台里,请为每一行使用一个主机名。
/profile=full-ha/subsystem=web/virtual-server=default-host/:write-attribute(name=alias,value=["localhost","example.com"])
Default Module
模块里的 web 应用程序应该部署在虚拟服务器的根节点,且 HTTP 请求里没有给出目录时将显示。
/profile=full-ha/subsystem=web/virtual-server=default-host/:write-attribute(name=default-web-module,value=ROOT.war)
配置 Web Services 选项

要配置 Web Services 选项,请点击 Web Services 菜单条目。下表解释了这些选项。

Expand
表 15.4. Web Services 的配置选项
选项 描述 CLI 命令
修改 WSDL 地址
指定应用程序是否可以修改 WSDL 地址。默认值是 true
/profile=full-ha/subsystem=webservices/:write-attribute(name=modify-wsdl-address,value=true)
WSDL 主机
JAX-WS Web Service 的 WSDL 合约包括 <soap:address> 元素,它指向端点的位置。如果 <soap:address> 的值是一个有效的 URL,除非设置 modify-wsdl-addresstrue,它不会被覆盖。如果 <soap:address> 的值不是一个有效的 URL,它会用 wsdl-hostwsdl-portwsdl-secure-port 的值进行覆盖。如果wsdl-host 被设置为 jbossws.undefined.host,覆盖 <soap-address> 时请求者的主机地址将被使用。它的默认值是 ${jboss.bind.address:127.0.0.1},当 JBoss EAP 6 启动时如果没有指定绑定地址,将使用 127.0.0.1
/profile=full-ha/subsystem=webservices/:write-attribute(name=wsdl-host,value=127.0.0.1)
WSDL 端口
用于重写 SOAP 端口的非安全端口。如果为 0(默认值),端口将通过查询安装的连接器列表来确定。
/profile=full-ha/subsystem=webservices/:write-attribute(name=wsdl-port,value=80)
WSDL 安全端口
用于重写 SOAP 端口的安全端口。如果为 0(默认值),端口将通过查询安装的连接器列表来确定。
/profile=full-ha/subsystem=webservices/:write-attribute(name=wsdl-secure-port,value=443)

15.2. 替换默认的 Welcome Web 应用程序

JBoss EAP 6 包含了一个 Welcome 应用程序,它在您访问服务器端口 8080 时显示。使用下列步骤,您可以用自己的 Web 应用程序替换这个程序。

过程 15.1. 用自己的 Web 应用程序替换默认的 Welcome 应用程序。

  1. 禁用 Welcome 应用程序。

    用管理 CLI 脚本 EAP_HOME/bin/jboss-cli.sh 运行下列命令。对于受管域,您可能需要修改受管域配置集;对于独立服务器,您可能需要删除 /profile=default
    /profile=default/subsystem=web/virtual-server=default-host:write-attribute(name=enable-welcome-root,value=false)
  2. 配置您的 Web 应用程序使用根上下文。

    要配置您的 Web 应用程序将根上下文(/)作为 URL 地址,请修改 META-INF/WEB-INF/ 目录下的 jboss-web.xml。用类似于下面的内容替换 <context-root> 指令。
    <jboss-web>
        <context-root>/</context-root>
    </jboss-web>		
    		
    
    
  3. 部署你的应用程序

    部署您的应用程序到服务器组或在第一个步骤修改的服务器里。这个应用程序应该可以通过这个地址访问:http://SERVER_URL:PORT/

第 16 章 HTTP 群集和负载平衡

16.1. 简介

16.1.1. 关于高可用性和负载平衡群集

群集(Clustering)指的是使用多个资源(如服务器),就好像单个实体一样。两个主要的群集类型是负载平衡(Load balancing,LB)群集高可用性(High-availability,HA)群集。在 LB 群集里,所由的资源都同时运行,管理层对工作负荷进行分配。
在 HA 群集里,当运行时某个资源,如果第一个不可用,将选择另外一个可用的资源。HA 群集的目的是降低硬件、软件或网络故障的影响。
JBoss EAP 6 支持不同级别的群集。高可用性的运行时组件和应用程序是:
  • 应用服务器实例
  • 和内部 JBoss Web 服务器、Apache HTTPD、Microsoft IIS 或 Oracle iPlanet Web 服务器一起使用的 Web 应用程序。
  • Stateful、stateless 和 Entity Enterprise JavaBeans (EJB)
  • 单点登录(Single Sign On,SSO)机制
  • 分布式缓存
  • HTTP 会话
  • JMS 服务和消息驱动 Bean(Message-driven beans,MDB)

16.1.2. 可从高可用性受益的组件

高可用性(HA)在 JBoss EAP 6 里分成更广的几个类别。
容器

JBoss EAP 6(作为独立服务器运行)的几个实例或服务器组的成员(作为受管域的一部分运行)可以配置为高可用的。这表示如果某个实例或成员停止或从群集消失,它的工作负荷将移至另外一个节点。工作负荷也可以通过这种方式提供负载平衡,所以具有更多、更好资源的服务器或服务器组可以承担更大部分的工作负荷,或者在高负荷时添加额外的能力。

Web 服务器

Web 服务器自身就可以使用某种兼容的负载平衡机制进行 HA 群集。最灵活的方式是 mod_cluster 连接器,它和 JBoss EAP 6 容器紧密地集成在一起。其他选择包含 Apache mod_jkmod_proxy 连接器或 ISAPI 和 NSAPI 连接器。

应用程序

根据 Java EE 6 规格,部署的应用程序也可以是高可用性的。 Stateless 或 stateful session EJB 可以进行群集,如果某个节点出现故障,另外一个节点可以接管。对于 stateful session bean,状态可以保持。

16.1.3. HTTP 连接器概述

JBoss EAP 6 可以使用构建到外部 HTTPD web 服务器的负载平衡和高可用性机制,如 Apache Web Server, Microsoft IIS 和 Oracle iPlanet。JBoss EAP 6 使用 HTTP 连接器和外部的 Web 服务器通讯。这些 HTTP 连接器是在 JBoss EAP 6 的 web 子系统里进行配置的。
HTTPD 服务器包含了控制 HTTP 请求路由至 JBoss EAP 6 工作节点的途径的软件模块。每个模块的工作模式和配置都有所不同。您可以配置这些模块在多个 JBoss EAP 6 服务器节点间平衡负载,或在发生故障时将负荷移至其他服务器。这两种能力分别被称为负载平衡(Load Balancing)高可用性(High Availability,HA)
JBoss EAP 6 支持几个不同的 HTTP 连接器。您要根据连接的 HTTPD 和需要的其他功能来进行选择。
下表列出了兼容 JBoss EAP 6 的 HTTP 连接器的不同之处。关于被支持的 HTTP 连接器的最新信息,请参考 https://access.redhat.com/site/articles/111663
Expand
表 16.1. HTTP 连接器功能和约束
连接器 Web 服务器 支持的操作系统 支持的协议 适用于部署状态 支持 Sticky Session
mod_cluster JBoss Enterprise Web Server HTTPD, Native HTTPD (Red Hat Enterprise Linux, Hewlett-Packard HP-UX) Red Hat Enterprise Linux, Microsoft Windows Server, Oracle Solaris, Hewlett-Packard HP-UX HTTP, HTTPS, AJP 是。检测应用程序的部署和卸载并根据应用程序是否部署在某个服务器上动态决定是否将请求指引到该服务器上。
mod_jk JBoss Enterprise Web Server HTTPD, Native HTTPD (Red Hat Enterprise Linux, Hewlett-Packard HP-UX) Red Hat Enterprise Linux, Microsoft Windows Server, Oracle Solaris, Hewlett-Packard HP-UX AJP 否。不管应用程序的状态,只要容器可用,就将请求指引到这个容器。
mod_proxy JBoss Enterprise Web Server HTTPD Red Hat Enterprise Linux\Microsoft Windows Server、Oracle Solaris HTTP, HTTPS, AJP 否。不管应用程序的状态,只要容器可用,就将请求指引到这个容器。
ISAPI Microsoft IIS Microsoft Windows Server AJP 否。不管应用程序的状态,只要容器可用,就将请求指引到这个容器。
NSAPI Oracle iPlanet Web Server Oracle Solaris AJP 否。不管应用程序的状态,只要容器可用,就将请求指引到这个容器。
JBoss EAP 6 支持的配置:https://access.redhat.com/site/articles/111663

16.1.4. 工作节点

HTTP 连接器节点

工作节点(worker node),有时候简称为节点,是从一个或多个面向客户的 HTTPD 服务器接受请求的 JBoss EAP 6 服务器。JBoss EAP 6 可以从自己的 HTTPD、JBoss EAP 6 附带的 HTTPD、Apache HTTPD、Microsoft IIS 或 Oracle iPlanet Web Server(以前是 Netscape Web Server)接受请求。

关于 JBoss EAP 6 支持的 HTTP 连接器概述以及如何进行配置的信息,请参考 第 16.1.3 节 “HTTP 连接器概述”
群集节点

群集节点(Cluster Node)是服务器群集里的成员。群集可以是负载平衡群集、高可用性群集,或者两者皆是。在负载平衡群集里,中央管理者根据不同的情况将负荷均匀地分摊到节点上。在高可用性群集里,某些节点积极运行,而其他节点则进行等待,当活动节点离开群集时开始运行。

16.2. 连接器配置

总结

JBoss EAP 6 里的线程池可以通过 Executor 模型在不同组件间共享。这些池不仅可以由不同的 HTTP 连接器共享,也可以被JBoss EAP 6 里支持 Executor 模型的其他组件共享。通过 HTTP 连接器线程池来满足当前的 Web 性能要求是件难办的事,它要求密切监控当前的线程池以及于其的负载需求。在本节里,您会学习如何通过 Executor 模型为 HTTP 连接器设立线程池。您也会学习通过命令行界面或编辑 XML 配置文件来进行设置。

过程 16.1. 为 HTTP 连接器设立线程池

  1. 定义线程工厂

    打开配置文件 standalone.xml(独立服务器)或 domain.xml(受管域)。这个文件位于 EAP_HOME/standalone/configurationEAP_HOME/domain/configuration 目录。
    添加下列子系统条目,按照您的服务器的需要修改相关的值。
    <subsystem xmlns="urn:jboss:domain:threads:1.0">
        <thread-factory name="http-connector-factory" thread-name-pattern="HTTP-%t" priority="9" group-name="uq-thread-pool"/>
    </subsystem>	
    
    
    如果您想用 CLI 来完成这个任务,请在 CLI 命令行提示下执行下列命令:
    [standalone@localhost:9999 /] ./subsystem=threads/thread-factory=http-connector-factory:add(thread-name-pattern="HTTP-%t", priority="9", group-name="uq-thread-pool")
  2. 创建执行器(Executor)

    您可以使用六种内置的 Executor 类来充当这个工厂的执行器。这六种执行器是:unbounded-queue-thread-poolbounded-queue-thread-poolblocking-bounded-queue-thread-poolqueueless-thread-poolblocking-queueless-thread-poolscheduled-thread-pool
    在这个例子里,我们将使用 unbounded-queue-thread-pool 来充当执行器。修改 max-threadskeepalive-time 参数的值来满足您的服务器的需要。
    <unbounded-queue-thread-pool name="uq-thread-pool">
      <thread-factory name="http-connector-factory" />
      <max-threads count="10" />
      <keepalive-time time="30" unit="seconds" />
    </unbounded-queue-thread-pool>			
    
    
    或者您更愿意使用 CLI:
    [standalone@localhost:9999 /] ./subsystem=threads/unbounded-queue-thread-pool=uq-thread-pool:add(thread-factory="http-connector-factory", keepalive-time={time=30, unit="seconds"}, max-threads=30)
  3. 让 HTTP 连接器使用这个线程池

    在相同的配置文件里,找到 web 子系统下的 HTTP 连接器元素并进行修改,让它使用之前步骤里定义的线程池。
    <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http" executor="uq-thread-pool" />
    
    或者您更愿意使用 CLI:
    [standalone@localhost:9999 /] ./subsystem=web/connector=http:write-attribute(name=executor, value="uq-thread-pool")
  4. 重启服务器

    重启服务器(独立服务器或受管域)让修改可以生效。请用下列 CLI 命令来确认上面步骤里的修改已经生效:
    [standalone@localhost:9999 /] ./subsystem=threads:read-resource(recursive=true)
    {                  
        "outcome" => "success",
        "result" => {
            "blocking-bounded-queue-thread-pool" => undefined,
            "blocking-queueless-thread-pool" => undefined,
            "bounded-queue-thread-pool" => undefined,
            "queueless-thread-pool" => undefined,
            "scheduled-thread-pool" => undefined,
            "thread-factory" => {"http-connector-factory" => {
                "group-name" => "uq-thread-pool",
                "name" => "http-connector-factory",
                "priority" => 9,
                "thread-name-pattern" => "HTTP-%t"
            }},
            "unbounded-queue-thread-pool" => {"uq-thread-pool" => {
                "keepalive-time" => {
                    "time" => 30L,
                    "unit" => "SECONDS"
                },
                "max-threads" => 30,
                "name" => "uq-thread-pool",
                "thread-factory" => "http-connector-factory"
            }}
        }
    }
    [standalone@localhost:9999 /] ./subsystem=web/connector=http:read-resource(recursive=true)
    {
        "outcome" => "success",
        "result" => {
            "configuration" => undefined,
            "enable-lookups" => false,
            "enabled" => true,
            "executor" => "uq-thread-pool",
            "max-connections" => undefined,
            "max-post-size" => 2097152,
            "max-save-post-size" => 4096,
            "name" => "http",
            "protocol" => "HTTP/1.1",
            "proxy-name" => undefined,
            "proxy-port" => undefined,
            "redirect-port" => 443,
            "scheme" => "http",
            "secure" => false,
            "socket-binding" => "http",
            "ssl" => undefined,
            "virtual-server" => undefined
        }
    }
    
结果

您已经创建一个线程工厂和执行器,而且修改了 HTTP 连接器来使用这个线程池。

16.3. HTTPD 配置

16.3.1. 关于独立 HTTPD

JBoss EAP 6 使用了 Red Hat 企业版 6 认证版本包含的 Apache HTTPD 进行测试和支持。Apache HTTPD 也可用于其他配置,如 Microsoft Windows Server。然而,既然 Apache HTTPD 是 Apache Foundation 创建的一个独立项目,确认用户使用的 Apache HTTPD 版本是否和 JBoss EAP 兼容通常是很困难的。
独立的 Apache HTTPD 现在是 JBoss EAP 6 附带的可单独下载的软件包。这简化了非 Red Hat 企业版 Linux 环境、或者已经配置了 HTTPD 但 Web 应用程序想使用单独实例的情况下的安装和配置。您可以从客户服务门户单独下载这个 HTTPD,它位于安装平台对应的 JBoss的 EAP 6 版本下。

16.3.2. 安装 JBoss EAP 6 附带的 Apache HTTPD(ZIP)

前提条件

  • 您需要根用户或管理员权限来完成这个任务。
  • 您必须安装 Apache Portability Runtime(APR)。在 Red Hat 企业版 Linux 里,安装下列软件包之一:apr-develapr-util-devel。如果您使用不同的操作系统,请参考 Apache Portability Runtime 网站 http://apr.apache.org/ 以符合要求。

过程 16.2. 安装 Apache HTTPD

  1. 在 Red Hat 客户服务门户找到对应您的平台的 JBoss EAP 下载列表。

    登录到 Red Hat 客户服务门户 https://access.redhat.com。使用顶部的菜单,选择 DownloadsJBoss Enterprise MiddlewareDownloads。从 Product 列表里选择 Application Platform。然后选择 JBoss EAP 的版本来查看该版本里可用的下载。
  2. 从列表里选择 HTTPD Binary。

    找到对应您的操作系统和架构的 HTTP Binary。点击 Download,下载 HTTPD 的 ZIP 文件到本地主机。
  3. 解压 ZIP 到要运行 HTTPD Binary 的位置。

    在您首选的服务器上解压 ZIP 文件到一个临时位置。ZIP 文件将创建 jboss-ews-version-number 下的 httpd 目录。复制 httpd 文件夹并将其放在您要安装 JBoss EAP 6 的目录里,这个目录通常被称为 EAP_HOME
    您的 HTTPD 现在位于 EAP_HOME/httpd/ 目录。正如其他 JBoss EAP 6 文档里找到的那样,您现在可以用 HTTPD_HOME 表示这个位置。
  4. 运行 Post-Installation 脚本并创建 apache 用户和组帐号

    在命令提示下,切换到根用户帐号,进入 EAP_HOME/httpd 目录并执行下列命令。
    ./.postinstall
    然后,通过下列命令检查是否存在名为 apache 的用户:
    id apache
    如果这个用户不存在,那您需要添加它及合适的用户组。为此,请执行下列命令:
    /usr/sbin/groupadd -g 91 -r apache 2> /dev/null || :
    /usr/sbin/useradd -c "Apache" -u 48 \ -s /sbin/nologin -r apache 2>
    /dev/null || :
    执行这个命令后,如果 apache 用户将运行 HTTPD 服务器,你需要修改 HTTP 目录的所有权:
    chown -R apache:apache httpd
    要测试上述命令是否执行成功,请检查 apache 用户是否具有对 HTTP 服务器安装路的执行权限。
    ls -l
    输出结果应该类似于:
    drwxrwxr-- 11 apache apache 4096 Feb 14 06:52 httpd
  5. 配置 HTTPD。

    用下列命令切换到新的用户帐号
    sudo su apache
    并配置 HTTPD 为 apache 用户来满足机构的需要。您可以参考 Apache Foundation 的文档:http://httpd.apache.org/
  6. 启动 HTTPD。

    用下列命令启动 HTTPD:
    EAP_HOME/httpd/sbin/apachectl start
  7. 停止 HTTPD。

    要停止 HTTPD,请执行下列命令:
    EAP_HOME/httpd/sbin/apachectl stop

前提条件

  • 您需要根用户或管理员权限来完成这个任务。
  • 您必须安装 Apache Portability Runtime(APR)。在 Red Hat 企业版 Linux 里,安装下列软件包之一:apr-develapr-util-devel。如果您使用不同的操作系统,请参考 Apache Portability Runtime 网站 http://apr.apache.org/ 以符合要求。
  • 您需要一个 Red Hat Network 的 BaseOS 频道的活动订阅。
  • 用下列命令安装 HTTPD:
    yum install httpd
    

16.3.4. httpd 上的 mod_cluster 配置

概述

mod_cluster 是一个基于 HTTPD 的负载平衡器。它使用一个通讯频道从 HTTPD 转发请求到应用服务器节点。您可以通过下面的 Derivative 配置 HTTPD 上的 mod_cluster。

注意

您不需要使用 ProxyPass directive,因为 mod_cluster 会自动配置必须转发给 JBossWEB 的 URL。
Expand
表 16.2. mod_cluster Derivatives
Derivative 描述
CreateBalancers 定义如何在 HTTPD 虚拟主机里创建负载平衡器。它允许这样的 directive: ProxyPass /balancer://mycluster1/
0: 创建 httpd 里定义的所有虚拟主机
1:不创建负载平衡器(定义平衡器名称要求至少一个 ProxyPass 或 ProxyMatch)
2: 只创建主服务器
默认值:2
使用这个值时,请不要忘记配置 ProxyPass directive 里的平衡器,因为默认值是一个空的 Sticky Session,nofailover=Off 和通过 MCMP CONFIG 消息接收的值都会被忽略。
UseAlias 检查别名是否对应服务器名。
0: 忽略别名
1: 检查别名
默认值:0
LBstatusRecalTime 重新计算节点状态的负载平衡逻辑的时间间隔(秒)。
默认值:5 秒钟
WaitForRemove 在已删除的节点被 HTTPD 忘记前的时间(秒)。
默认值:10 秒
ProxyPassMatch/ProxyPass
ProxyPassMatch 和 ProxyPass 是 mod_proxy directive,当使用 !(而非 back-end url)时阻止路径里的 reverse-proxy。它用于允许 HTTPD 服务于静态信息,如图像。例如:
ProxyPassMatch ^(/.*\.gif)$ !
上面的例子允许 HTTPD 直接保存 .gif 文件。
mod_manager

除非特别说明,在所有情况下,mod_manger directive 的上下文都是 VirtualHost。server config 上下文暗示 directive 必须位于 VirtualHost 配置的外面。如果没有,则会显示错误信息且不会启动 HTTPD。

Expand
表 16.3. mod_manager Derivatives
Derivative 描述
EnableMCPMReceive 允许 VirtualHost 从节点接收 MCPM。HTTPD 配置文件里包含的 EnableMCPMReceive 可以允许 mod_cluster 运行。配置 Advertise 时请将它保存在 VirtualHost 里。
MemManagerFile
mod_manager 用来保存配置、为共享内存生成密钥或锁定文件的基础名称。它必须是一个绝对路径名;如果需要可以创建 directive。我们推荐将这些文件置于本地驱动而非 NFS 共享目录里。
Context: server config
$server_root/logs/
Maxcontext mod_cluster 支持的上下文的最大数量
Context: server config
默认值:100
Maxnode mod_cluster 支持的节点的最大数量
Context: server config
默认值:20
Maxhost mod_cluster 支持的主机(别名)的最大数量。它也包含平衡器的最大数目。
Context: server config
10
Maxsessionid
保存的活动 sessionid 的数量,它提供 mod_cluster-manager 处理程序里活动会话的数量。当 mod_cluster 在 5 分钟内没有从会话里接收信息时,会话将变成不活动的。
Context: server config
这个字段只适用于演示和调试目的。
0:逻辑没被激活。
MaxMCMPMaxMessSize 来自其他 Max Directive 的 MCMP 消息的最大尺寸 从其他 Max Directive 进行计算。最小值:1024
ManagerBalancerName 当 JBoss AS/JBossWeb/Tomcat 没有提供平衡器名称时使用的平衡器名称。
mycluster
PersistSlots 告诉 mod_slotmem 将节点、别名和上下文保存到文件里。
Context: server config
Off
CheckNonce 当使用 mod_cluster-manager 处理程序时切换 Nonce 检查
on/off
默认:on - Nonce 检查
AllowDisplay 在 mod_cluster-manager 主页面上切换其他显示信息。
on/off
默认:off - 只显示版本号
AllowCmd 允许使用 mod_cluster-manager URL 的命令。
on/off
默认:on - 允许的命令
ReduceDisplay 减少显示在主 mod_cluster-manager 页面上的信息,所以在这个页面上可以显示更多的节点。
on/off
默认:off - 显示全部信息
SetHandler mod_cluster-manager
显示 mod_cluster 从群集里看到的节点的信息。这些信息包括普通信息活动会话的数量。
						
							<Location /mod_cluster-manager>
							SetHandler mod_cluster-manager
							Order deny,allow
							Allow from 127.0.0.1
							</Location>
						

on/off
默认值:off

注意

当访问 httpd.conf 里定义的位置时:
Transferred:对应发送到后台服务器的 POST 数据。
Connected:对应请求 mod_cluster 状态页面时已被处理的请求的数量。
Num_sessions:对应 mod_cluster 报告为活动的会话的数量(过去 5 分钟有请求)。如果 Maxsessionid 为 0,这个字段不会出现。这个字段只适用于演示和调试目的。
概述

关于将外部 HTTPD 用作 Web 前端的原因,以及 JBoss EAP 6 支持的不同 HTTP 连接器的优缺点,请参考 第 16.1.3 节 “HTTP 连接器概述”。在某些情况下,您可以使用操作系统附带的 HTTPD。否则,您可以使用 JBoss Enterprise Web Server 里附带的 HTTPD。

在您已决定使用哪个 HTTPD 和 HTTP 连接器后,请参考下列过程之一:

16.3.6. 配置 JBoss EAP 6 从外部 HTTPD 接受请求

概述

JBoss EAP 6 不需要直到它从中接受请求的代理,只需要直到端口和协议。但 mod_cluster 不是这样的,它和JBoss EAP 6 的配置耦合得更紧密。下列步骤适用于 mod_jkmod_proxyISAPINSAPI。请用自己的设置替换这个例子里的协议和端口。

要配置 JBoss EAP 6 的 mod_cluster,请参考 第 16.5.6 节 “配置 mod_cluster 工作节点”

前提条件

过程 16.3. 编辑配置并添加套接字绑定

  1. 配置 jvmRouteuseJK 系统属性。

    在默认情况下,jvmRoute 会被设置为服务器名称。如果您需要定制,您可以使用下列命令。根据您使用的配置集或独立服务器,替换或删除命令的 /profile=ha 部分。用你自己的 jvmRoute 替换 CUSTOM_ROUTE_NAME
    [user@localhost:9999 /] /profile=ha/subsystem=web:write-attribute(name="instance-id",value="CUSTOM_ROUTE_NAME")
    用下列命令将 useJK 设置为 true 以启用它:
    [user@localhost:9999 /] /system-property=UseJK/:add(value=true)
  2. 列出 Web 子系统可用的连接器。

    注意

    这个步骤只有在使用独立服务器的 standalone-ha.xml 配置或受管域的 hafull-ha 配置集时才需要。这些配置已经包含了必需的连接器。
    为了使外部的 HTTPD 可以连接 JBoss EAP 6 的 Web 服务器,Web 子系统需要一个连接器。每个协议都需要自己的连接器,它绑定到套接字组上。
    要列出当前可用的连接器,请使用下列命令:
    [standalone@localhost:9999 /] /subsystem=web:read-children-names(child-type=connector)
    如果没有指定您需要的连接器(如 HTTP、HTTPS 、AJP),您需要添加连接器。
  3. 读取连接器的配置。

    要查看连接器配置的细节,您可以读取它的配置。下列命令读取 AJP 连接器的配置。其他连接器具有类似的配置输出。
    [standalone@localhost:9999 /] /subsystem=web/connector=ajp:read-resource(recursive=true)
    {
        "outcome" => "success",
        "result" => {
            "enable-lookups" => false,
            "enabled" => true,
            "max-post-size" => 2097152,
            "max-save-post-size" => 4096,
            "protocol" => "AJP/1.3",
            "redirect-port" => 8443,
            "scheme" => "http",
            "secure" => false,
            "socket-binding" => "ajp",
            "ssl" => undefined,
            "virtual-server" => undefined
        }
    }		
    
    
  4. 将必需的连接器添加到 Web 子系统里。

    要添加连接器到 Web 子系统里,您需要一个套接字绑定。这个套接字绑定应添加到您的服务器或服务器组使用的套接字绑定组里。下面的步骤假设您的服务器组是 server-group-one,套接字绑定组是 standard-sockets
    1. 添加套接字到套接字绑定组里。

      要添加套接字到套接字绑定组,请执行下列命令(替换协议和端口)。
      [standalone@localhost:9999 /] /socket-binding-group=standard-sockets/socket-binding=ajp:add(port=8009)
    2. 添加套接字绑定到 Web 子系统里。

      执行下列命令将连接器添加到 Web 子系统里(替换套接字绑定名和协议)。
      [standalone@localhost:9999 /] /subsystem=web/connector=ajp:add(socket-binding=ajp, protocol="AJP/1.3", enabled=true, scheme="http")

16.4. 群集

16.4.1. Clustering 子系统使用 TCP 通讯

在默认情况下,群集节点用 UDP 协议监控其他节点的状态。某些网络只允许使用 TCP。在这种情况下,您可以在配置里添加 TCPPING 协议栈并将作为默认机制。基于命令行的管理 CLI 里也有这些配置选项。
mod_cluster 子系统默认也使用 UDP 通讯,但您可以选择使用 TCP。
参考下列两个过程配置 JGroups 和 mod_cluster 子系统以使用 TCP 网络通讯:

16.4.2. 配置 JGroups 系统使用 TCP

在默认情况下,JGroups 系统使用多点传送 UDP 通讯。使用下列过程来配置 JGroups 系统使用多点传送 TCP。
要配置 mod_cluster 子系统使用 TCP,请参考 第 16.4.3 节 “禁用 mod_cluster 子系统的广告”
  1. 运行 CLI。

    在 Linux 里用 EAP_HOME/bin/jboss-cli.sh 命令、在 Windows 服务器里使用 EAP_HOME\bin\jboss-cli.bat 命令启动管理 CLI。输入 connect 连接到 localhost 上的域控制器,或 connect IP_ADDRESS 连接到远程服务器上的域控制器。
  2. 根据您的环境修改下列脚本。

    复制下列脚本到文本编辑器里。如果您使用受管域里不同的配置集,请相应地修改配置集名称。如果您使用独立服务器,请删除命令行里的 /profile=full-ha 部分。像下面这样修改命令底部列出的属性。这些属性都是可选的。
    initial_hosts
    用逗号隔开的主机列表,里面的主机被认为是众所周知的,可用来查找初始成员资格。
    port_range
    如果需要,您可以分配一个端口范围。如果您分配的端口范围为 2,而初始端口为 7600,那么 TCPPING 将试图连接每台主机的 7600-7601 端口。这个属性是可选的。
    timeout
    群集成员的可选超时时间(毫秒)。
    num_initial_members
    在群集被认为完成之前的节点数。这个属性是可选的。
    cd /profile=full-ha/subsystem=jgroups
    ./stack=tcpping:add
    cd stack=tcpping
    ./transport=TRANSPORT:add(type=TCP,socket-binding=jgroups-tcp)
    :add-protocol(type=TCPPING)
    :add-protocol(type=MERGE2)
    :add-protocol(type=FD_SOCK,socket-binding=jgroups-tcp-fd)
    :add-protocol(type=FD)
    :add-protocol(type=VERIFY_SUSPECT)
    :add-protocol(type=BARRIER)
    :add-protocol(type=pbcast.NAKACK)
    :add-protocol(type=UNICAST2)
    :add-protocol(type=pbcast.STABLE)
    :add-protocol(type=pbcast.GMS)
    :add-protocol(type=UFC)
    :add-protocol(type=MFC)
    :add-protocol(type=FRAG2)
    :add-protocol(type=RSVP)
    cd protocol=TCPPING
    ./property=initial_hosts/:add(value="HostA[7600],HostB[7600]")
    ./property=port_range/:add(value=0)
    ./property=timeout/:add(value=3000)
    ./property=num_initial_members/:add(value=3) 
    cd ../..
    :write-attribute(name=default-stack,value=tcpping)
    
  3. 以批处理方式运行脚本。

    警告

    运行这个配置集的服务器必须在执行批处理文件前先关闭。
    在管理 CLI 提示下,输入 batch 并按 Enter 键。命令行提示符会包含一个井字键(#),表示处于批处理模式。这允许您输入一系列命令。如果其中任何一个命令失败,整个操作将被回滚。
    粘贴之前步骤里修改的脚本,在结尾再添加一个新行。输入 run-batch 来运行批处理命令。在所有命令都已运行后,将会出现 The batch executed successfully 信息。
结果

TCPPING 栈对于 JGroups 子系统不可用。如果使用它,JGroups 子系统将对所有网络通讯使用 TCP。要配置 mod_cluster 子系统使用 TCP,请参考 第 16.4.3 节 “禁用 mod_cluster 子系统的广告”

16.4.3. 禁用 mod_cluster 子系统的广告

在默认情况下, mod_cluster 子系统的平衡器使用多点传送 UDP 来广播其功能到后台 Worker。如果您愿意,您可以禁用广告。请用下列命令来配置这种行为。

过程 16.4. 

  1. 修改 HTTPD 配置。

    修改 HTTPD 配置来禁用服务器广告并使用代理列表。代理列表在 Worke上配置,包含它可以对话的所有启用了 mod_cluster 的 HTTPD。
    HTTPD 服务器的 mod_cluster 配置通常位于 /etc/httpd/ 或 HTTPD 安装的 etc/httpd/ 目录里(对于非标准安装)。关于这个文件的更多信息,请参考 第 16.5.3 节 “安装 mod_cluster 模块至 Apache HTTPD 或 JBoss Enterprise Web Server HTTPD (ZIP)”第 16.5.5 节 “为启用 mod_cluster 的 HTTPD 配置服务器的 Advertisement 属性”。打开包含侦听 MCPM 请求(使用 EnableMCPMReceive 指令)的虚拟主机的文件,并通过修改 ServerAdvertise 指令禁用服务器广告。
    ServerAdvertise Off
  2. 禁用 JBoss EAP 6 里的 mod_cluster 子系统的广告并提供一个代理列表。

    通过基于 Web 的管理控制台或命令行管理 CLI,您可以禁用 mod_cluster 子系统的广告提供一个代理列表。因为如果禁用广告,mod_cluster 子系统无法自动发现代理,所以这个代理列表是必需的。
    • 管理控制台

      1. 如果您使用受管域,您只可以在启用 mod_cluster 的配置集里配置它,如 hafull-ha 配置集。
      2. 登录到管理控制台并选择屏幕右上角的 Profiles。如果您使用的是受管域,请从 Profiles 页面左上角的 Profiles 里选择 hafull-ha 配置集。
      3. 点击 Subsystems 菜单展开它。展开 Web 子菜单并选择 Modcluster
      4. 点击顶部的 Edit 按钮,编辑属于整个 mod_cluster 子系统的选项。修改 Advertise 的值为 false。用 Save 按钮保存设置。
      5. 点击屏幕底部的 Proxies 标签。点击 Proxies 子页面的 Edit 按钮,并输入代理服务器列表。正确的语法是逗号隔开的 HOSTNAME:PORT 字符串列表,如:
        10.33.144.3:6666,10.33.144.1:6666
        点击 Save 按钮保存修改。
    • 管理 CLI

      下面的两个管理 CLI 命令创建了和上面的管理控制台相同的配置。它们假设您运行的是受管域且您的服务器组使用了 full-ha 配置集。如果您使用了不同的配置,请在命令里修改名称。如果你使用了运行 standalone-ha 配置集的独立服务器,请从命令里删除 /profile=full-ha
      /profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=advertise,value=false)
      
      /profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=proxy-list,value="10.33.144.3:6666,10.33.144.1:6666")
      
结果

HTTPD 平衡器不再向工作节点广播且不再使用 UDP 多点传送。

16.5. Web、HTTP 连接器和 HTTP 群集

16.5.1. 关于 mod_cluster HTTP 连接器

mod_cluster 是在 JBoss Web 容器里启用负载平衡的模块。它被称为 connector。使用哪个连接器取决于您用于 JBoss EAP 6 的 Web 容器。要了解其他连接器的详情,请参考下面的内容:
mod_cluster 连接器有几个优势。
  • mod_cluster Management Protocol (MCMP) 是应用服务器节点和 HTTPD 之间的一个额外连接,应用服务器节点使用它通过自定义的 HTTP 方法集来传输服务器端的负载平衡因子及生命周期事件到 Web 容器。
  • HTTPD 代理的动态配置允许 JBoss EAP 6 可在运行时进行修改而无需额外的配置。
  • 应用服务器执行负载平衡器因子的计算。这使得负载平衡度量比其他连接器更为准确。
  • mod_cluster 提供了应用程序生命周期的细颗粒度控制。每个服务器将任何 Web 应用程序上下文生命周期事件转发给代理,通知它启动停止对服务器里给定上下文的路由请求。这避免了最终用户看到由于不可用资源引起的 404 错误。
  • 您可以使用 AJP、HTTP、带有 mod_cluster 的 HTTPS 和 Apache HTTP。

16.5.2. 配置 mod_cluster 子系统

在基于 Web 的管理控制台里,mod_cluster 选项是 Web 子系统配置区域里的一部分。点击左上角的 Profiles 标签页。如果你使用的是受管域,请从右上角的 Profile 选单里选择正确的配置集。在默认情况下,hafull-ha 配置集都启用了 mod_cluster 子系统。如果您使用的是独立服务器,您需要使用 standalone-hastandalone-full-ha 配置集来启动服务器。点击左侧菜单的 Web 条目并在子菜单里选择 mod_cluster。下表解释了这些选项。首先是总体配置,然后是会话、Web 上下文、代理、SSL 和网络的配置。每项配置在 mod_cluster 屏幕里都有单独的标签页。

注意

mod_cluster 配置页只对启用了 HA 群集子系统的配置集可见。这些配置集包括用于受管域的 hafull-ha,或者用于独立服务器的 standalone-hastandalone-full-ha
Expand
表 16.4. mod_cluster 配置选项
选项 描述 CLI 命令
Load Balancing Group
如果它不为 null,请求会被发送到专门的负载平衡器上的负载平衡组。如果您不想使用负载平衡组,请将其留空。它默认是没被设置的。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=load-balancing-group,value=myGroup)
Balancer
平衡器的名称。它应该匹配 HTTPD 代理的配置。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=balancer,value=myBalancer)
Socket / Secure Socket
用于群集广告的套接字绑定的名称。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=advertise-socket,value=modcluster)
Advertise Security Key
包含用于广告的安全密钥的字符串。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=advertise-security-key,value=myKey)
Advertise
是否启用广告。默认为 true
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=advertise,value=true)
Expand
表 16.5. mod_cluster 会话配置选项
选项 描述 CLI 命令
Sticky Session
是否对请求使用 Sticky Session。这意味着在客户连接至专有的群集节点后,进一步的通讯将路由至相同的节点,除非这个节点不可用。它默认为 true,也是我们推荐的设置。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=sticky-session,value=true)
Sticky Session Force
如果为 true,如果初始节点不可用,请求不会重定向到新的群集节点。相反,系统会报告失败。默认值为 false
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=sticky-session-force,value=false)
Sticky Session Remove
在失效时删除会话信息。默认是禁用的。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=sticky-session-remove,value=false)
Expand
表 16.6. mod_cluster 的 Web Context 上下文配置选项
选项 描述 CLI 命令
Auto Enable Contexts
是否默认添加新的上下文到 mod_cluster。默认值是 true。如果您修改这个默认值来设置手动启用上下文,Web 应用程序将用 enable() MBean 方法、 或者通过 mod_cluster(它是一个运行在虚拟主机和端口的 HTTPD 代理上的 Web 应用程序)启用它的上下文。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=auto-enable-contexts,value=true)
Excluded Contexts
mod_cluster 应该忽略的用逗号隔开的上下文列表。如果没有指定主机,会假定主机是 localhostROOT 表示 Web 应用程序的根上下文。默认值是 ROOT,invoker,jbossws,juddi,console
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=excluded-contexts,value="ROOT,invoker,jbossws,juddi,console")
Expand
表 16.7. mod_cluster 的代理配置选项
选项 描述 CLI 命令
Proxy URL
如果指定,MCMP 命令的 URL 里将预置它的值。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=proxy-url,value=myhost)
Proxy List
A comma-separated list of HTTPD proxy addresses, in the format hostname:port. This indicates the list of proxies that the mod_cluster process will attempt to communicate with initially.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=proxy-list,value="127.0.0.1,127.0.0.2")
配置 mod_cluster 的 SSL 通讯

在默认情况下,mod_cluster 通讯基于未加密的 HTTP 链接上。如果您设置连接器模式为 HTTPS(请参考 表 16.5 “mod_cluster 会话配置选项”),下面的设置将告诉 mod_cluster 在哪寻找加密连接的信息。

Expand
表 16.8. mod_cluster 的 SSL 配置选项
选项 描述 CLI 命令
ssl
是否启用 SSL。默认值为 false
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=ssl,value=true)
Key Alias
密钥别名,当创建证书时进行选择。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=key-alias,value=jboss)
Key Store
包含客户证书的密钥库的位置
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=key-store,value=System.getProperty("user.home") + "/.keystore")
Key Store Type
密钥库的类型
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=key-store-type,value=JKS)
密钥库供应商
密钥库供应商
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=key-store-provider,value=IBMJCE)
密码
密码,当创建证书时进行选择。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=password,value=changeit)
Trust Algorithm
信任管理工厂的算法。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=trust-algorithm,value=PKIX)
Cert File
证书文件的位置。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=ca-certificate-file,value=${user.home}/jboss.crt)
CRL File
证书撤销列表文件。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=ca-crl-file,value=${user.home}/jboss.crl)
Max Certificate Length
信任库里的存储的证书的最大长度。默认为 5。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=trust-max-cert-length,value=5)
Key File
证书的密钥文件的位置。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=certificate-key-file,value=${user.home}/.keystore)
Cipher Suite
分配的加密密文套件
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=cipher-suite,value=ALL)
Certificate Encoding Algorithms
密钥管理工厂的算法。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=encoding-algorithms,value=ALL)
撤销 URL
证书授权撤销列表的 URL。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=ca-revocation-url,value=jboss.crl)
Protocol
启用的 SSL 协议。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=protocol,value=SSLv3)
配置 mod_cluster 网络选项

可用的 mod_cluster 网络选项控制 mod_cluster 与之通讯的几个不同类型的服务的不同的超时行为。

Expand
表 16.9. mod_cluster 网络配置选项
选项 描述 CLI 命令
Node Timeout
节点的代理连接的超时时间(秒)。这是 mod_cluster 在返回错误前等待后台响应的时间。它对应工作节点的 mod_proxy 文档里描述的超时时间。-1 表示不会超时。请注意,在转发请求前 mod_cluster 总是使用 cping/cpong,而 mod_cluster 使用的 connectiontimeout 值时一个 Ping 值。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=node-timeout,value=-1)
Socket Timeout
等待 HTTPD 代理到 MCMP 命令的响应并标记代理为错误状态的超时时间(毫秒)。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=socket-timeout,value=20)
Stop Context Timeout
等待上下文(分布式上下文的待定请求完成;或非分布式上下文的活动会话销毁/过期)干净关闭的时间,它按照 stopContextTimeoutUnit 指定的单元衡量。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=stop-context-timeout,value=10)
会话消耗策略
在卸载 Web 应用程序前是否耗尽会话。
DEFAULT
如果 Web 应用程序是非分布式的,在 Web 应用程序卸载以前耗尽会话。
ALWAYS
在 Web 应用程序(即使是非分布式 Web 应用程序)卸载以前总是耗尽会话。
NEVER
在 Web 应用程序(即使是非分布式 Web 应用程序)卸载以前不会耗尽会话。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=session-draining-strategy,value=DEFAULT)
Max Attempts
在放弃前,HTTP 代理试图发送给定请求到工作节点的最大次数。最小值是 1,表示只尝试一次。mod_proxy 的默认值也是 1,表示不尽心重试。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=max-attempts,value=1)
Flush Packets
是否启用 HTTPD 服务器的数据包冲刷。默认值为 false
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=flush-packets,value=false)
Flush Wait
在冲刷数据包到 HTTPD 服务器前等待的时间(秒)。默认值是 -1-1 表示在冲刷数据包前无限期地等待。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=flush-wait,value=-1)
Ping
等待群集节点响应的时间(秒)。默认值为 10 秒。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=ping,value=10)
SMAX
最大的 soft 空闲连接数目(和 mod_proxy 文档里的 smax 相同)。最大值取决于 httpd 线程的配置,它可以是 ThreadsPerChild1
profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=smax,value=ThreadsPerChild)
TTL
超出 SMAX 的空闲连接可存活的时间(秒),默认为 60。
当没有定义 nodeTimeout 时,ProxyTimeout 指令 Proxy 将被使用。如果没有定义 ProxyTimeout,服务器的 Timeout 将被使用。其默认值是 300 秒。nodeTimeoutProxyTimeoutTimeout 都是在套接字级别设置的。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=ttl,value=-1)
Node Timeout
等待外部 HTTPD 服务器的可用 Workder 进程处理请求的时间(秒)。默认值是 -1,表示 mod_cluster 会无限期地等待 HTTPD Worker 处理请求。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=node-timeout,value=-1)
mod_cluster 的负载提供者配置选项

下面的 mod_cluster 配置选项在基于 Web 的管理控制台里是不可用的,只能用 CLI 命令行来设置。

如果未定义动态负载处理器,简单的负载处理器将被使用。它赋予每个群集成员负载因子 1,并均匀地分布负载而不用考虑任何负载平衡算法。要添加它,请使用下列 CLI 命令:/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/simple-load-provider:add
您可以配置动态的加载提供者使用不同的算法来确定哪个群集节点接收下一个请求。默认的动态加载提供者使用 busyness 因子。下面可能的因子列表。您可以创建自己的加载提供者以满足环境的需要。您可以修改下面的动态提供者选项。请注意,您可以通过 CLI 添加多个因子(度量)。
:add-metric(type=cpu)
Expand
表 16.10. mod_cluster 的动态负载提供者选项
选项 描述 CLI 命令
Decay
历史度量影响力消退的因子
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/:write-attribute(name=decay,value=2)
History
确定负载时考虑历史负载度量记录的数量。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/:write-attribute(name=history,value=9)
Load Metric
JBoss EAP 6 的动态负载提供者包含的唯一负载度量是 busyness,它会尝试发送每个新的请求到最空闲的工作节点。您可以设置工作节点的能力(1 表示 100%)以及分配给 busyness 度量的总体权重。
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=busyness/:write-attribute(name=capacity,value=1.0)
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=busyness/:write-attribute(name=type,value=busyness)
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=busyness/:write-attribute(name=weight,value=1)

Load Metric 算法

cpu
cpu 负载度量使用了平均 CPU 负载来确定哪个群集节点接受下一个工作负荷。
mem
mem 负载度量将空闲的原生 RAM 用作负载因子。我们不鼓励使用这个度量,因为它提供的是包含缓冲和缓存的值,所以在内存管理良好的系统里它总是一个非常低的值。
heap
heap 负载度量使用 heap 用度来确定哪个群集接受下一个工作负荷。
sessions
session 负载度量使用活动会话的数量作为度量。
requests
requests 负载度量使用了客户请求的数量来确定哪个群集节点接受下一个工作负荷。例如,1000 表示 1000 个请求/秒会被认作“满负荷”。
send-traffic
send-traffic 负载度量使用了从工作节点发送到客户的流量。例如,默认的 512 表示如果平均的转出流量是 512KB/s 或更高时节点应该被当作满负荷状态。
receive-traffic
receive-traffic 负载度量使用了从客户发送到工作节点的流量。例如,默认的 1024 表示如果平均的转入流量是 1024KB/s 或更高时节点应该被当作满负荷状态。
busyness
这个度量代表了服务于请求的线程池的线程的数量。

例 16.1. 设置负载平衡器的度量

/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=cpu/:write-attribute(name="weight",value="3")

前提条件

  • 要执行这个任务,您必须使用安装在 Red Hat 企业版 Linux 6 里的 Apache HTTPD 或JBoss Enterprise Web Server,或者作为 JBoss EAP 6 可下载组件的独立 HTTPD。
  • 如果你需要在 Red Hat 企业版 Linux 6 里安装 Apache HTTPD,请使用《Red Hat Enterprise Linux 6 部署指南》里的说明。这些说明可在 https://access.redhat.com/site/documentation/ 上找到。
  • 如果您需要安装作为 JBoss EAP 6 的可下载组件的独立的 HTTPD,请参考 第 16.3.2 节 “安装 JBoss EAP 6 附带的 Apache HTTPD(ZIP)”
  • 如果你需要安装 JBoss Enterprise Web Server,请使用《JBoss Enterprise Web Server 安装指南》里的说明。这些说明可在 https://access.redhat.com/site/documentation/ 上找到。
  • 根据操作系统和架构从 Red Hat 客户入口 https://access.redhat.com 下载 Webserver Connecter Natives 软件包。这个软件包包含为操作系统预编译的 mod_cluster 的 HTTPD 模块,这些模块位于 modules/native/lib/httpd/modules/ 目录。
    etc/ 目录包含一些配置文件示例,而 share/ 目录则包含一些补充文档。
  • 您必须用管理员权限(root)登录。

过程 16.5. 安装 mod_cluster 模块

  1. 确定您的 HTTPD 配置的位置。

    根据您是否使用 Red Hat 企业版 Linux 的 Apache HTTPD、JBoss EAP 6 是否包含作为可下载组件的独立 HTTPD、JBoss Enterprise Web Server 里是否有可用的 HTTPD,HTTPD 配置文件的位置会有所不同。
    • Apache HTTPD - /etc/httpd/
    • JBoss EAP 6 HTTPD - 根据您的系统架构需求选择的位置。
    • JBoss Enterprise Web Server HTTPD - EWS_HOME/httpd/
  2. 复制这些模块到 HTTPD 的 modules 目录。

    从解压的 Webserver Natives 归档的 modules/native/lib/httpd/modules/ 目录复制四个模块(以 .so 结尾的文件)到 HTTPD_HOME/modules/ 目录。
  3. 对于 JBoss Enterprise Web Server,请禁用 mod_proxy_balancer 模块。

    如果您使用 JBoss Enterprise Web Server,mod_proxy_balancer 默认是启用的。它和 mod_cluster 不兼容。要禁用它,请编辑 HTTPD_HOME/conf/httpd.conf 并用 # 注释下列加载模块的内容。下面的内容没有显示注释符号。
    LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
    # LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
    保存并关闭文件。
  4. 配置 mod_cluster 模块。

    Webserver Natives 归档包含一个 mod_cluster.conf 示例文件(modules/system/layers/base/native/etc/httpd/conf)。这个文件可用作模版或通过复制/编辑来创建 HTTPD_HOME/httpd/conf.d/JBoss_HTTP.conf 文件。

    注意

    这个文档里的习惯是使用 JBoss_HTTP.conf。这个配置文件如果保存在 conf.d/ 目录里,且扩展名为 .conf,它就会被加载。
    在配置文件里加入下列内容:
    LoadModule slotmem_module modules/mod_slotmem.so
    LoadModule manager_module modules/mod_manager.so
    LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
    LoadModule advertise_module modules/mod_advertise.so
    
    这会让 Apache HTTPD 自动加载 mod_cluster 运行所需的模块。
  5. 创建一个代理服务器 listener。

    继续编辑 HTTPD_HOME/httpd/conf.d/JBoss_HTTP.conf 并添加下列配置,用适合您系统的值替换调大写字母表示的值。
    Listen IP_ADDRESS:PORT
    <VirtualHost IP_ADDRESS:PORT>  
    	  <Location />
              Order deny,allow
              Deny from all
              Allow from *.MYDOMAIN.COM
    	  </Location>
    	  
    	  KeepAliveTimeout 60
    	  MaxKeepAliveRequests 0
    	  EnableMCPMReceive On
    	  
    	  ManagerBalancerName mycluster
    	  ServerAdvertise On
    	  
    </VirtualHost>
    
    这些指令创建了一个新的虚拟服务器,它侦听 IP_ADDRESS:PORT,允许来自 MYDOMAIN.COM 的连接,并将自己作为 mycluster 负载平衡器进行广告。Apache Web Server 的文档会深入讨论这些指令。要学习 ServerAdvertiseEnableMCPMReceive 指令以及服务器广告的含义,请参考 第 16.5.5 节 “为启用 mod_cluster 的 HTTPD 配置服务器的 Advertisement 属性”
    保存文件并退出。
  6. 重启 HTTPD。

    重启 HTTPD 的方法取决于您是否使用 Red Hat 企业版 Linux 的 Apache HTTPD 或包含在 JBoss Enterprise Web Server 里的 HTTPD。从下面两个方法里选择一个。
    • Red Hat Enterprise Linux 6 Apache HTTPD

      运行下列命令:
      [root@host]# service httpd restart
    • JBoss Enterprise Web Server HTTPD

      JBoss Enterprise Web Server 既可以运行在 Red Hat Enterprise Linux 也可以运行在 Microsoft Windows Server 上。两者重启 HTTPD 的方法是不同的。
      • Red Hat Enterprise Linux

        在 Red Hat 企业版 Linux 里,JBoss Enterprise Web Server 将 HTTPD 安装为服务。要重启 HTTPD,执行下面两个命令:
        [root@host ~]# service httpd stop[root@host ~]# service httpd start
        
        
      • Microsoft Windows Server

        用管理员权限执行下列命令:
        C:\> net stop httpdC:\> net start httpd
        
        
结果

Apache HTTPD 现在已配置为负载平衡器,且可以和运行 JBoss EAP 6 的 mod_cluster 子系统一起工作。要使 JBoss EAP 6 可以意识到 mod_cluster,请参照 第 16.5.6 节 “配置 mod_cluster 工作节点”

前提条件

  • 要执行这个任务,您必须使用安装在 Red Hat 企业版 Linux 6 里的 Apache HTTPD 或JBoss Enterprise Web Server,或者作为 JBoss EAP 6 可下载组件的独立 HTTPD。
  • 如果你需要在 Red Hat 企业版 Linux 6 里安装 Apache HTTPD,请使用《Red Hat Enterprise Linux 6 部署指南》里的说明。这些说明可在 https://access.redhat.com/site/documentation/ 上找到。
  • 如果您需要安装作为 JBoss EAP 6 的可下载组件的独立的 HTTPD,请参考 第 16.3.2 节 “安装 JBoss EAP 6 附带的 Apache HTTPD(ZIP)”
  • 如果你需要安装 JBoss Enterprise Web Server,请使用《JBoss Enterprise Web Server 安装指南》里的说明。这些说明可在 https://access.redhat.com/site/documentation/ 上找到。
  • 您必须用管理员权限(root)登录。
  • 您必须有活动的 jbappplatform-6-ARCH-server-VERS-rpm RHN 频道的订阅。
RPM 安装方法对于 Red Hat 企业版 Linux 5 和 6 来说都是类似的,只是要求安装了 Apache HTTPD 2.2.15 的 Red Hat 企业版 Linux 6 用户有少许的变化。
  1. 用 YUM 安装 mod_cluster-native 软件包:
    yum install mod_cluster-native
    
  2. HTTPD 2.2.15:
    • 如果您选择使用 HTTPD 2.2.15,您必须通过注释 httpd.conf 文件里的 LoadModule proxy_balancer_module 行来禁用 mod_proxy_balancer 模块。
      用下列命令或手动编辑这个文件:
      sed -i 's/^LoadModule proxy_balancer_module/#LoadModule proxy_balancer_module/;s/$//' /etc/httpd/conf/httpd.conf
      
    • 如果您选择升级到 HTTPD 2.2.22,请用下列命令安装最新的版本。
      yum install httpd
      
  3. 要在引导时启动 HTTPD 服务,请执行下列命令:
    service httpd add
    
  4. 用下列命令启动 mod_cluster 平衡器:
    service httpd start
    
总结

关于用 mod_cluster 负载平衡器配置 HTTPD 的说明,请参考 第 16.5.3 节 “安装 mod_cluster 模块至 Apache HTTPD 或 JBoss Enterprise Web Server HTTPD (ZIP)”。需要进一步说明的配置是 server advertisement

当启用 Server Advertisement 时,HTTPD 会广播包含在 mod_cluster 虚拟机里指定的 IP 地址和端口的消息。关于如何配置这些值,请参考 第 16.5.3 节 “安装 mod_cluster 模块至 Apache HTTPD 或 JBoss Enterprise Web Server HTTPD (ZIP)”。如果您的网络里 UDP 多点传送不可用,或者你更希望用静态代理服务器列表来配置工作节点,您可以禁用 Server Advertisement 并手动配置工作节点。关于配置工作节点的信息,请参考 第 16.5.6 节 “配置 mod_cluster 工作节点”
这个过程里的修改必须在和 Apache HTTPD 实例相关的httpd.conf 里进行。对于 Red Hat 企业版 Linux,这个文件通常是 /etc/httpd/conf/httpd.conf,或者位于独立 Apache HTTPD 实例的 etc/ 目录里。

过程 16.6. 编辑 httpd.conf 文件并应用这些修改。

  1. 如果 AdvertiseFrequency 参数存在,则禁用它。

    如果你的 <VirtualHost> 语句里有下面一行内容,请在第一个字符前用 # (hash) 将其注释。这个值可以不是 5
    AdvertiseFrequency 5
  2. 添加指令来禁用服务器广告。

    <VirtualHost> 语句里添加下列指令来禁用服务器广告。
    ServerAdvertise Off
  3. 禁用接收 MCPM 消息的能力。

    添加下列指令到 HTTPD 服务器来从工作节点接收 MCPM 消息。
    EnableMCPMReceive On
  4. 重启 HTTPD 服务器。

    根据你使用的是 Red Hat 企业版 Liux 还是 Microsoft Windows Server,通过下列命令之一重启 HTTPD 服务器。
    • 红帽企业版 Linux

      [root@host ]# service httpd restart
    • Microsoft Windows Server

      C:\> net service http
      C:\> net service httpd start
      
结果

HTTPD 不再广告 mod_cluster 代理的 IP 地址和端口。如要重新激活,您需要配置工作节点使用静态地址和端口来和代理进行通讯。详情请参考 第 16.5.6 节 “配置 mod_cluster 工作节点”

16.5.6. 配置 mod_cluster 工作节点

介绍

mod_cluster 工作节点由一个 JBoss EAP 服务器组成。这个服务器可以是受管域里服务器组的一部分,也可以是一个独立服务器。JBoss EAP 里运行的一个独立进程管理这个群集的所有节点。它被称为主节点(Master)。关于工作节点的更多概念,请参考 第 16.1.4 节 “工作节点”。关于 HTTPD 负载平衡的概述,请参考 第 16.1.3 节 “HTTP 连接器概述”

主节点只需要通过 mod_cluster 子系统配置一次。要配置 mod_cluster 子系统,请参考《管理和配置指南》里的『配置 mod_cluster 子系统』。每个工作节点都是独立配置的,所以你可以为每个要加入群集的节点重复这个步骤。
如果你使用了受管域,服务器组里的每个服务器都是一个工作节点,它们共享相同的配置。因此,配置是对于整个服务器组完成的。而在独立服务器里,配置是对于单个 JBoss EAP 6 实例完成的。其余的配置步骤是相同的。

工作节点配置

  • 如果你使用了独立服务器,它必须以 standalone-ha 配置集启动。
  • 如果你使用受管域,你的服务器组必须使用 hafull-ha 配置集,以及 ha-socketsfull-ha-sockets 套接字绑定组。JBoss EAP 6 附带满足这些要求的启用了群集的服务器组 other-server-group

注意

如果使用管理 CLI 命令,它会假设你使用受管域。如果你使用的是独立服务器,请从命令行删除 /profile=full-ha

过程 16.7. 配置工作节点

  1. 配置网络接口。

    在默认情况下,网络接口都是 127.0.0.1。每个容纳独立服务器或服务器组里的一个或多个服务器的物理主机的接口都需要进行配置以使用其他服务器可以看到的公共 IP 地址。
    要修改 JBoss EAP 6 主机的 IP 地址,你需要关闭它并直接修改配置文件。这是因为驱动管理控制台和管理 CLI 的 Management API 依赖于稳定的管理地址。
    遵循下列步骤将群集里的每个服务器的 IP 地址修改为主节点的公共 IP 地址。
    1. 完全地关闭服务器。
    2. 对于受管域,编辑位于 EAP_HOME/domain/configuration/ 里的 host.xml,而对于独立服务器,编辑位于 EAP_HOME/standalone/configuration/ 里的 standalone-ha.xml
    3. 找到 <interfaces> 元素。有三个接口需要配置,managementpublicunsecured。你都要修改 127.0.0.1 为主机的外部 IP 地址。
    4. 对于参与受管域但不是主节点的主机,找到 <host 元素。请注意,它没有结尾的 > 符号,这是因为它包含了属性。将其 name 属性从 master 修改为其他的唯一名称,每个从节点都应不同。这个名称也将被从节点用来标识群集,请注意这一点。
    5. 对于需要加入受管域的刚配置好的主机,找到 <domain-controller> 元素。注释或删除 <local /> 元素,并添加下列一行,修改 IP 地址(X.X.X.X)为域控制台的地址。这个步骤不适用于独立服务器。
      <remote host="X.X.X.X" port="${jboss.domain.master.port:9999}" security-realm="ManagementRealm"/>
      
    6. 保存文件并退出。
  2. 为每个从服务器配置验证。

    每个从服务器都需要在域控制器或独立主服务器的 ManagementRealm 里创建一个用户名和密码。在域控制器或独立主服务器上,运行 EAP_HOME/bin/add-user.sh 命令。请用和从服务器相同的用户名添加一个用户到 ManagementRealm。当提示这个用户是否需要到外部的 JBoss AS 实例验证,请选择 yes。下面是这个命令的输入和输出的例子,从服务器名为 slave1,其密码为 changeme
    user:bin user$ ./add-user.sh
    
    What type of user do you wish to add? 
     a) Management User (mgmt-users.properties) 
     b) Application User (application-users.properties)
    (a): a
    
    Enter the details of the new user to add.
    Realm (ManagementRealm) : 
    Username : slave1
    Password : changeme
    Re-enter Password : changeme
    About to add user 'slave1' for realm 'ManagementRealm'
    Is this correct yes/no? yes
    Added user 'slave1' to file '/home/user/jboss-eap-6.0/standalone/configuration/mgmt-users.properties'
    Added user 'slave1' to file '/home/user/jboss-eap-6.0/domain/configuration/mgmt-users.properties'
    Is this new user going to be used for one AS process to connect to another AS process e.g. slave domain controller?
    yes/no? yes
    To represent the user add the following to the server-identities definition <secret value="Y2hhbmdlbWU=" />
    
  3. add-user.sh 的输出里复制 Base64 编码的 <secret> 元素。

    如果你计划验证时指定 Base64 编码的密码,请复制 add-user.sh 的输出里的 <secret> 元素值,你在下面的步骤里需要用到它。
  4. 修改从主机的安全区以使用新的验证。

    1. 重新打开从主机的 host.xmlstandalone-ha.xml 文件。
    2. 找到 <security-realms> 元素。这是你配置安全区(Security Realm)的地方。
    3. 你可以用下列方法之一指定 secret 值:
      • 在配置文件里指定 Base64 编码的密码值。

        1. <security-realm name="ManagementRealm"> 行下添加下列 XML 片段:
          <server-identities>
              <secret value="Y2hhbmdlbWU="/>
          </server-identities>
                          
          
          
        2. 用前一步骤的 add-user.sh 输出里返回的 secret 值来替换 "Y2hhbmdlbWU=" 。
      • 配置主机通过 vault.sh 获取密码。

        1. 使用 vault.sh 脚本生成一个加密的密码。它将生成一个这样的字符串: VAULT::secret::password::ODVmYmJjNGMtZDU2ZC00YmNlLWE4ODMtZjQ1NWNmNDU4ZDc1TElORV9CUkVBS3ZhdWx0
          你可以在本指南的『敏感字符串的密码阀』里找到更多信息:第 10.13.1 节 “关于保护明码文件里的敏感字符”
        2. <security-realm name="ManagementRealm"> 行下添加下列 XML 片段:
          <server-identities>
              <secret value="${VAULT::secret::password::ODVmYmJjNGMtZDU2ZC00YmNlLWE4ODMtZjQ1NWNmNDU4ZDc1TElORV9CUkVBS3ZhdWx0}"/>
          </server-identities>
                          
          
          
          请用前一步骤生成的加密密码替换 secret 值。

          注意

          当在阀里创建一个密码时,它必须以明文而不是 Base64 编码来指定。
      • 指定密码为系统属性。

        1. <security-realm name="ManagementRealm"> 行下直接添加下列 XML 代码块。
          <server-identities>
              <secret value="${server.identity.password}"/>
          </server-identities>
                          
          
          
        2. 当你将密码指定为系统属性时,你可以用下列方法之一配置主机:
          • 在命令行里以明文输入密码来启动服务器,例如:
            -Dserver.identity.password=changeme

            注意

            密码必须以明文输入并对于任何执行 ps -ef 命令的用户可见。
          • 将密码放在属性文件里并将文件的 URL 作为命令行参数传入。
            1. 在属性文件里添加键/值对。例如:
              server.identity.password=changeme
              
            2. 用命令行参数启动服务器:
              --properties=URL_TO_PROPERTIES_FILE
              .
    4. 保存文件并退出。
  5. 重启服务器。

    从主机现在将以主机名为用户名以及加密的字符串为密码来向主服务器进行验证。
结果

你的独立服务器,或者位于受管域的服务器组里的服务器,现在已被配置为 mod_cluster 工作节点。如果你部署一个群集应用程序,它的会话会被复制到所有的群集节点以用于失效切换,且它可以从外部的 HTTPD 服务器或负载平衡器接受请求。在默认情况下,群集的每个节点都可以用自动发现来发现其他节点。要配置自动发现和 mod_cluster 子系统的其他专有设置,请参考 第 16.5.2 节 “配置 mod_cluster 子系统”。要配置 Apache HTTPD 服务器,请参考 第 16.3.5 节 “将外部 HTTPD 用作 JBoss EAP 6 应用程序的 Web 前端”

16.5.7. 在群集间移植流量

总结

在用 JBoss EAP 6 创建新的群集后,作为升级过程的一部分,您可能希望从之前的群集移植流量到新的群集里。在本节里,您会看到用于移植流量且只造成最短时间中断或停机的策略。

前提条件

过程 16.8. 群集的升级过程

  1. 用预备条件里描述的步骤设置新的群集。
  2. 在 Cluster NEW 和 Cluster OLD 里,请确保配置选项 sticky-session 设置为 true(默认为 true)。启用这个选项意味着对群集的所有新的请求都将继续发送到该节点。
    /profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=sticky-session,value=true)
    
  3. 通过这里描述的过程添加 Cluster NEW 里的节点到 mod_cluster 配置里:第 16.5.6 节 “配置 mod_cluster 工作节点”
  4. 配置负载平衡器(mod_cluster)来停止群集 Cluster OLD 里的单个上下文。停止上下文(对比禁用它)将允许单个上下文优雅地关闭(最终关闭整个节点)。现有的会话将仍被服务,但不会有新的会话被指引到这些节点。被停止的上下文可能需要几分钟才能完成停止动作。
    您可以用下列 CLI 命令来停止某个上下文。用和您环境相关的值替换这些参数。
    [standalone@localhost:9999 subsystem=modcluster] :stop-context(context=/myapp, virtualhost=default-host, waittime=50)
结果

您已经成功升级了 JBoss EAP 6 群集。

16.6. Apache mod_jk

16.6.1. 关于 Apache mod_jk HTTP 连接器

Apache mod_jk 是一个用于兼容性目的的 HTTP 连接器。Apache mod_jk 提供了负责平衡功能,这是 JBoss Web Container 里包含的 jboss-eap-native-webserver-connectors 的一部分。对于所支持的平台,请参考 https://access.redhat.com/site/articles/111663mod_jk 连接器是由 Apache 维护的,它的文档位于 http://tomcat.apache.org/connectors-doc/
JBoss EAP 6 可以从 Apache HTTPD 代理服务器接受工作负荷。代理服务器从 Web 前端接受客户请求,并将工作负荷传递给参与的 JBoss EAP 6 服务器。如果启用了 sticky session,相同的客户请求总会进入相同的 JBoss EAP 6 服务器,除非服务器不可用。
不像 JBoss mod_cluster HTTP 连接器,Apache 代理服务器不会直到服务器或服务器组上的部署的状态,在发送工作负荷时也无法适应。
就像 AJP 1.3 协议只上的 mod_clustermod_jk 通讯。

注意

mod_cluster 是一个比 mod_jk 更高级的负载平衡器。mod_cluster 提供了 mod_jk 所有的功能以及其他功能。关于 mod_cluster 的更多信息,请参考 第 16.5.1 节 “关于 mod_cluster HTTP 连接器”

16.6.2. 配置 JBoss EAP 6 用 Apache Mod_jk 进行通讯

概述

mod_jk HTTP 连接器由一个单一组件,由 HTTPD 加载的 mod_jk.so 模块。这个模块接收客户请求并将其转发到容器,这个例子里是 JBoss EAP 6。您也需要配置 JBoss EAP 6 来接受请求并将回复发送到 HTTPD。

为了 JBoss EAP 6 能够与 Apache HTTPD 服务器通讯,它需要启用 AJP/1.3 HTTPD 连接器。在 下列配置里这个连接器默认是启用的:
  • 在受管域或使用 hafull-ha 的服务器组里,以及hafull-ha 套接字绑定组里。默认安装里正确地配置了 other-server-group 服务器组。
  • 在独立服务器里,standalone-hastandalone-full-ha 是为群集配置的。要用这些配置集启动独立服务器,请从 EAP_HOME/ 目录执行下列命令,并用合适的配置集进行替换。
    [user@host bin]$ ./bin/standalone.sh --server-config=standalone-ha.xml

前提条件

  • 要执行这个任务,您必须使用安装在受支持环境里的 Apache HTTP 服务器或安装在 JBoss Enterprise Web Server 里的 Apache HTTP 服务器。请注意,JBoss Enterprise Web Server 里安装的 Apache HTTP 服务器是 JBoss EAP 6 的一部分。
  • 如果您需要安装 Apache HTTP 服务器,请使用 https://access.redhat.com/site/documentation/《Red Hat 企业版 Linux 部署指南》里的说明。
  • 如果您需要安装 JBoss Enterprise Web Server,请参照《JBoss Enterprise Web Server 安装指南》里的说明,它位于 https://access.redhat.com/site/documentation/
  • 如果您在使用 Apache HTTP 服务器,请从 Red Hat 客户入口下载 JBoss EAP 6 Native 组件软件包 https://access.redhat.com。这个软件包包含为 Red Hat 企业版 Linux 编译的 mod_jk 和 mod_cluster。如果您使用的是 JBoss Enterprise Web 服务器,它已经包含了 mod_jk。
  • 您必须用管理员权限(root)登录。

过程 16.9. 安装 mod_jk 模块

  1. 配置 mod_jk 模块

    1. 创建一个名为 HTTPD_HOME/conf.d/mod-jk.conf 的文件并添加下列内容:

      注意

      JkMount 指令指定 Apache 应该转发哪些 URL 到 mod_jk 模块。根据指令的配置,mod_jk 将接收到的 URL 转发到正确的 Servlet 容器。
      要直接服务静态内容且只使用本地负载平衡器,URL 路径应该为 /application/*。要将 mod_jk 用作负载平衡器,请使用 /* 将所有 URL 转发给 mod_jk。
      # Load mod_jk module
      # Specify the filename of the mod_jk lib
      LoadModule jk_module modules/mod_jk.so
      
      # Where to find workers.properties
      JkWorkersFile conf/workers.properties
      
      # Where to put jk logs
      JkLogFile logs/mod_jk.log
      
      # Set the jk log level [debug/error/info]
      JkLogLevel info 
      
      # Select the log format
      JkLogStampFormat  "[%a %b %d %H:%M:%S %Y]"
      
      # JkOptions indicates to send SSK KEY SIZE
      JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
      
      # JkRequestLogFormat
      JkRequestLogFormat "%w %V %T"
      
      # Mount your applications
      # The default setting only sends Java application data to mod_jk.
      # Use the commented-out line to send all URLs through mod_jk.
      # JkMount /* loadbalancer
      JkMount /application/* loadbalancer
      
      # Add shared memory.
      # This directive is present with 1.2.10 and
      # later versions of mod_jk, and is needed for
      # for load balancing to work properly
      JkShmFile logs/jk.shm 
      
      # Add jkstatus for managing runtime data
      <Location /jkstatus/>
      JkMount status
      Order deny,allow
      Deny from all
      Allow from 127.0.0.1
      </Location>
      
      
      查看这些值,确保它们是合理的,然后保存文件。
    2. 指定 JKMountFile 指令

      除了 mod-jk.conf 里的 JKMount 指令以外,您可以指定一个包含多个转发到 mod_jk 的 URL 模式的文件。
      1. 添加下列内容到 HTTPD_HOME/conf/mod-jk.conf 文件:
        # You can use external file for mount points.
        # It will be checked for updates each 60 seconds.
        # The format of the file is: /url=worker
        # /examples/*=loadbalancer
        JkMountFile conf/uriworkermap.properties
        
      2. 创建一个名为 HTTPD_HOME/conf/uriworkermap.properties 的新文件,其中每一行对应一个 URL 模式。下面的例子展示了这个文件的语法。
        # Simple worker configuration file
        /*=loadbalancer
        
    3. 复制 mod_jk.so 文件到 HTTPD 的 modules 目录

      注意

      只有您的 HTTPD 在其 modules/ 目录下没有 mod_jk.so 时它才是必需的。如果您在使用 JBoss EAP 6 里包含的 Apache HTTPD 服务器,您可以跳过这个步骤。
      解压 Native Web Server Connectors ZIP 软件包。在 EAP_HOME/modules/native/lib/httpd/modules/EAP_HOME/modules/native/lib64/httpd/modules/ 目录里找到 mod_jk.so 文件(根据操作系统是 32 还是 64 位的)。
      复制文件到 HTTPD_HOME/modules/ 目录。
  2. 配置 mod_jk 工作节点。

    1. 创建一个名为 HTTPD_HOME/conf/workers.properties 的文件。使用下面的例子作为起点,并根据需要进行修改。
      # Define list of workers that will be used
      # for mapping requests
      worker.list=loadbalancer,status
      
      # Define Node1
      # modify the host as your host IP or DNS name.
      worker.node1.port=8009
      worker.node1.host=node1.mydomain.com
      worker.node1.type=ajp13
      worker.node1.ping_mode=A
      worker.node1.lbfactor=1 
      
      # Define Node2
      # modify the host as your host IP or DNS name.
      worker.node2.port=8009
      worker.node2.host=node2.mydomain.com
      worker.node2.type=ajp13
      worker.node2.ping_mode=A
      worker.node2.lbfactor=1
      
      # Load-balancing behavior
      worker.loadbalancer.type=lb
      worker.loadbalancer.balance_workers=node1,node2
      worker.loadbalancer.sticky_session=1
      
      # Status worker for managing load balancer
      worker.status.type=status
      
      关于 workers.properties 文件的详细描述和高级配置选项,请参考 第 16.6.5 节 “Apache Mod_jk 工作节点的配置”
  3. 重启 HTTPD。

    重启 HTTPD 的方法取决于您是否使用 Red Hat 企业版 Linux 的 Apache HTTPD 或包含在 JBoss Enterprise Web Server 里的 HTTPD。从下面两个方法里选择一个。
    • Red Hat 企业版 Linux 的 Apache HTTPD

      运行下列命令:
      [root@host]# service httpd restart
    • JBoss Enterprise Web Server HTTPD

      JBoss Enterprise Web Server 既可以运行在 Red Hat Enterprise Linux 也可以运行在 Microsoft Windows Server 上。两者重启 HTTPD 的方法是不同的。
      • Red Hat 企业版 Linux(通过 RPM 安装)

        在 Red Hat 企业版 Linux 里,JBoss Enterprise Web Server 将 HTTPD 安装为服务。要重启 HTTPD,执行下面两个命令:
        [root@host ~]# service httpd stop
        [root@host ~]# service httpd start
        
      • Red Hat 企业版 Linux(通过 ZIP 安装)

        如果您已经通过 ZIP 归档安装了 JBoss Enterprise Web Server 的 HTTPD,请使用 apachectl 命令来重启 HTTPD。请用您解压 JBoss Enterprise Web Server HTTPD 的目录来替换 EWS_HOME
        [root@host ~]# EWS_HOME/httpd/sbin/apachectl restart
        
      • Microsoft Windows Server

        用管理员权限执行下列命令:
        C:\> net stop Apache2.2
        C:\> net start Apache2.2
        
      • Solaris

        请在命令行提示下用有管理权限的用户执行下列命令。请用您解压 JBoss Enterprise Web Server HTTPD 的目录来替换 EWS_HOME
        [root@host ~] EWS_HOME/httpd/sbin/apachectl restart
        
结果

已配置 Apache HTTPD 使用 mod_jk 负载平衡器。要使 JBoss EAP 6 可以意识到 mod_jk,请参照 第 16.3.6 节 “配置 JBoss EAP 6 从外部 HTTPD 接受请求”

16.6.4. 安装 Mod_jk 模块至 Apache HTTP Server (RPM)

前提条件

  • 要执行这个任务,您必须使用安装在受支持环境里的 Apache HTTP 服务器或安装在 JBoss Enterprise Web Server 里的 Apache HTTP 服务器。请注意,JBoss Enterprise Web Server 里安装的 Apache HTTP 服务器是 JBoss EAP 6 的一部分。
  • 如果您需要安装 Apache HTTP 服务器,请使用 https://access.redhat.com/site/documentation/《Red Hat 企业版 Linux 部署指南》里的说明。
  • 如果你需要安装 JBoss Enterprise Web Server,请使用《JBoss Enterprise Web Server 安装指南》里的说明。这些说明可在 https://access.redhat.com/site/documentation/ 上找到。
  • 您必须用管理员权限(root)登录。

过程 16.10. Red Hat 企业版 Linux 5:mod_jk 和 Apache HTTP Server 2.2.3

  1. jbappplatform-6-*-server-5-rpm 频道安装 mod_jk-ap22 1.2.37 及其依赖关系 mod_perl:
    yum install mod_jk
    
  2. Optional: 复制配置文件示例:
    cp /usr/share/doc/mod_jk-ap22-1.2.37/mod_jk.conf.sample /etc/httpd/conf.d/mod_jk.conf
    
    cp /usr/share/doc/mod_jk-ap22-1.2.37/workers.properties.sample /etc/httpd/conf/workers.properties
    
    您可以根据需要编辑这些文件。
  3. 启动服务器:
    service httpd start
    

注意

下列错误信息表示您的 mod_jk 模块在 mod_perl 之前被加载:
Cannot load /etc/httpd/modules/mod_jk.so into server: /etc/httpd/modules/mod_jk.so: undefined symbol: ap_get_server_description
要确保 mod_perl 模块在 mod_jk 之前加载,请在 /etc/httpd/conf.d/mod_jk.conf 里添加下列内容:
 <IfModule !perl_module>
        LoadModule perl_module modules/mod_perl.so
</IfModule>
LoadModule jk_module modules/mod_jk.so

过程 16.11. Red Hat 企业版 Linux 5:mod_jk 和 JBoss EAP Apache HTTP Server 2.2.22

  1. 用下列命令从 jbappplatform-6-*-server-5-rpm 频道安装 mod_jk 和最新的 Apache HTTP Server 2.2.22:
    yum install mod_jk httpd
    
  2. Optional: 复制配置文件示例:
    cp /usr/share/doc/mod_jk-ap22-1.2.37/mod_jk.conf.sample /etc/httpd/conf.d/mod_jk.conf
    
    cp /usr/share/doc/mod_jk-ap22-1.2.37/workers.properties.sample /etc/httpd/conf/workers.properties
    
    您可以根据需要编辑这些文件。
  3. 启动服务器:
    service httpd start
    

过程 16.12. Red Hat 企业版 Linux 6:mod_jk 和 JBoss EAP Apache HTTP Server 2.2.22

  1. jbappplatform-6-*-server-6-rpm 频道安装 mod_jk-ap22 1.2.37 和 Apache HTTP Server 2.2.22 httpd 软件包(任何先有的版本将被更新):
    yum install mod_jk httpd
    
  2. Optional: 复制配置文件示例:
    cp /usr/share/doc/mod_jk-ap22-1.2.37/mod_jk.conf.sample /etc/httpd/conf.d/mod_jk.conf
    
    cp /usr/share/doc/mod_jk-ap22-1.2.37/workers.properties.sample /etc/httpd/conf/workers.properties
    
    您可以根据需要编辑这些文件。
  3. 启动服务器:
    service httpd start
    

过程 16.13. Red Hat 企业版 Linux 6:mod_jk 和 Apache HTTP Server 2.2.15

  1. 用下列命令安装 mod_jk 和 Apache HTTP Server 2.2.15:
    yum install mod_jk
    
  2. Optional: 复制配置文件示例:
    cp /usr/share/doc/mod_jk-ap22-1.2.37/mod_jk.conf.sample /etc/httpd/conf.d/mod_jk.conf
    
    cp /usr/share/doc/mod_jk-ap22-1.2.37/workers.properties.sample /etc/httpd/conf/workers.properties
    
    您可以根据需要编辑这些文件。
  3. 启动服务器:
    service httpd start
    

16.6.5. Apache Mod_jk 工作节点的配置

workers.properties 文件定义 mod_jk 传递客户请求的工作节点的行为。在 Red Hat 企业版 Linux 里,这个文件位于 /etc/httpd/conf/workers.propertiesworkers.properties 文件定义不同的 Servlet 容器的位置,以及在它们之间如何平衡负载。
这个配置分成三个部分。第一部分处理全局属性,它应用于所有的工作节点。第二部分包含应用于专有节点的设置。第三部分包含应用于专有的采用负载平衡的节点。
属性的常用结构是 worker.WORKER_NAME.DIRECTIVE,这里的 WORKER_NAME 是工作节点的唯一名称,而 DIRECTIVE 是应用在工作节点上的设置。
Apache Mod_jk 工作节点的配置参考

节点模版指定默认的 per-node 设置。您可以在节点设置里覆盖模版。示例模版位于 例 16.2 “workers.properties 示例文件”

Expand
表 16.11. 全局属性
属性 描述
worker.list mod_jk 使用的工作节点列表。这些工作节点可用来接收请求。
Expand
表 16.12. 基于每个工作节点的属性
属性 描述
type
工作节点的类型。默认类型是 ajp13。其他可能的值还有 ajp14lbstatus
关于这些指令的详情,请参照 http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html 里的 Apache Tomcat Connector AJP Protocol 参考。
balance_workers
指定负载平衡器必须管理的工作节点。对于同一个负载平衡器您可以多次使用这个指令。它由一个用逗号隔开的工作节点名列表组成。它是根据每个工作节点而不是节点设置的。它影响该工作节点类型的所有节点。
sticky_session
指定来自相同会话的请求是否总是路由至相同的工作节点。默认值是 0,表示禁用 Sticky Session。要启用 Sticky Session,请将其设置为 1。Sticky Session 通常应该被启用,除非所有的请求都是 stateless 的。这是针对每个工作节点而非节点设置的。它影响该工作节点类型的所有节点。
Expand
表 16.13. 基于每个节点的属性
属性 描述
host
工作节点的主机名和 IP 地址。工作节点必须支持 ajp 协议栈。默认值是 localhost
port
侦听定义的协议请求的远程服务器实例的端口号码。默认值是 8009,这也是 AJP13 工作节点的默认侦听端口。AJP14 工作节点的默认端口是 8011。
ping_mode
连接在哪些条件下会检测网络状态。探测仪用空的 AJP13 数据包进行 CPing,期望有 CPong 回应。使用指令标记组合来指定条件。这些标记不是用逗号或空格分隔的。 ping_mode 可以是任何 CPIA 的组合。
  • C - Connect。在连接至服务器后探测连接一次。用 connect_timeout 的值指定超时时间。否则使用 ping_timeout
  • P - Prepost。在发送每个请求到服务器之前探测连接。用 prepost_timeout 指令指定超时时间。否则使用 ping_timeout
  • I - Interval。根据 connection_ping_interval 指定的时间间隔来探测连接。否则使用 ping_timeout
  • A - All。CPI 的快捷方式,它指定使用所有的连接探测仪。
ping_timeout, connect_timeout, prepost_timeout, connection_ping_interval
连接探测仪设置的超时值。这些值的单位是毫秒, ping_timeout 的默认值是 10000。
lbfactor
为独立工作节点指定负载因子,且只应用于负载平衡器的成员工作节点。这便于为高性能的服务器赋予更多的工作负载。要赋予某个工作节点 3 倍的默认负载,将其设置为 3worker.my_worker.lbfactor=3

例 16.2. workers.properties 示例文件

worker.list=node1, node2, node3
     
worker.balancer1.sticky_sessions=1
worker.balancer1.balance_workers=node1
worker.balancer2.sticky_session=1
worker.balancer2.balance_workers=node2,node3

worker.nodetemplate.type=ajp13
worker.nodetemplate.port=8009

worker.node1.template=nodetemplate
worker.node1.host=localhost
worker.node1.ping_mode=CI
worker.node1.connection_ping_interval=9000
worker.node1.lbfactor=1

worker.node2.template=nodetemplate
worker.node2.host=192.168.1.1
worker.node2.ping_mode=A

worker.node3.template=nodetemplate
worker.node3.host=192.168.1.2
Apache mod_jk 的进一步的配置细节超出了本文档的范畴。更多的说明请参考 http://tomcat.apache.org/connectors-doc/ 上的 Apache 文档。

16.7. Apache mod_proxy

16.7.1. 关于 Apache mod_proxy HTTP 连接器

Apache 为 HTTPD 提供两个不同的代理和负载平衡模块:mod_proxymod_jk。要进一步了解 mod_jk,请参考 第 16.6.1 节 “关于 Apache mod_jk HTTP 连接器”。JBoss EAP 6 支持这两种模块,但 JBoss HTTP 连接器 mod_cluster 和 JBoss EAP 6 及外部 HTTPD 耦合得更紧密,且是我们推荐的 HTTPD 连接器。关于所有支持的 HTTP 连接器的概述,以及其优缺点,请参考 第 16.1.3 节 “HTTP 连接器概述”
不像 mod_jkmod_proxy 支持基于 HTTP 和 HTTPS 协议的连接。它们也支持 AJP 协议。
mod_proxy 可以在独立服务器或负载平衡器里配置,它也支持 Sticky Session 标记。
mod_proxy 模块要求 JBoss EAP 6 配置 HTTP、HTTPS 或 AJP web connector。这是 Web 子系统的一部分。关于配置 Web 子系统的信息,请参考 第 15.1 节 “配置 Web 子系统”

16.7.2. 安装 Mod_proxy HTTP 连接器到 Apache HTTPD

概述

mod_proxy 是 Apache 提供的一个 load-balancing 模块。这个任务代表了一个简单的配置。关于更高级的配置或其他细节,请参考 Apache 的 mod_proxy 文档 https://httpd.apache.org/docs/2.2/mod/mod_proxy.html。关于从 JBoss EAP 6 角度来看的 mod_proxy 细节,请参考 第 16.7.1 节 “关于 Apache mod_proxy HTTP 连接器”第 16.1.3 节 “HTTP 连接器概述”

前提条件

  • JBoss Enterprise Web Server 的 HTTPD 或 Apache HTTP 服务器都需要先安装。独立的 Apache HTTP 服务器在 Red Hat 客户门户 https://access.redhat.com 里是可以单独下载的。关于这个 HTTPD 的信息,请参考 第 16.3.2 节 “安装 JBoss EAP 6 附带的 Apache HTTPD(ZIP)”
  • mod_proxy 模块需被安装。Apache HTTP 服务器通常带有 mod_proxy 模块。对于 Red Hat 企业版 Linux,JBoss Enterprise Web Server 附带了 Apache HTTP 服务器。
  • 您需要 root 或管理员权限来修改 Apache HTTP 服务器的配置。
  • 在这些例子里,我们假设 JBoss EAP 6 配置了 HTTP 或 HTTPS Web 连接器。这是 Web 子系统配置的一部分。关于配置 Web 子系统的信息,请参考 第 15.1 节 “配置 Web 子系统”
  1. 启用 HTTPD 里的 mod_proxy 模块

    HTTPD_HOME/conf/httpd.conf 文件里寻找下列行。如果没有,则在文件结尾添加它们。如果存在但是以注释符号(#)开始的,请删除这些符号。保存文件。通常这些模块都会存在且已启用。
    LoadModule proxy_module modules/mod_proxy.so
    LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
    LoadModule proxy_http_module modules/mod_proxy_http.so
    # Uncomment these to proxy FTP or HTTPS
    #LoadModule proxy_ftp_module modules/mod_proxy_ftp.so
    #LoadModule proxy_connect_module modules/mod_proxy_connect.so
    
  2. 添加 non-load-balancing 代理。

    Add the following configuration to your HTTPD_HOME/conf/httpd.conf file, directly beneath any other <VirtualHost> directives you may have. Replace the values with ones appropriate to your set-up.
    这个例子使用了虚拟主机。请参考下一个步骤来使用默认的 HTTPD 配置。
    <VirtualHost *:80>
    # Your domain name
    ServerName Domain_NAME_HERE
    
    ProxyPreserveHost On
    
    # The IP and port of JBoss EAP 6
    # These represent the default values, if your HTTPD is on the same host
    # as your JBoss EAP 6 managed domain or server
    
    ProxyPass / http://localhost:8080/
    ProxyPassReverse / http://localhost:8080/
    
    # The location of the HTML files, and access control information
    DocumentRoot /var/www
    <Directory /var/www>
    Options -Indexes
    Order allow,deny
    Allow from all
    </Directory>
    </VirtualHost>
    
    在进行修改后,保存这个文件。
  3. 添加 load-balancing 代理。

    要将 mod_proxy 用作负载平衡器,并将工作负载发送到多个 JBoss EAP 6 服务器,请添加下列配置到 HTTPD_HOME/conf/httpd.conf 文件里。这个 IP 地址是虚构的。请用自己的值来替换它。
    <Proxy balancer://mycluster>
    
    Order deny,allow
    Allow from all
    
    # Add each JBoss Enterprise Application Server by IP address and port.
    # If the route values are unique like this, one node will not fail over to the other.
    BalancerMember http://192.168.1.1:8080 route=node1
    BalancerMember http://192.168.1.2:8180 route=node2
    </Proxy>
    
    <VirtualHost *:80>
     # Your domain name
     ServerName YOUR_DOMAIN_NAME
    
     ProxyPreserveHost On
     ProxyPass / balancer://mycluster/
    
     # The location of the HTML files, and access control information DocumentRoot /var/www
     <Directory /var/www>
      Options -Indexes
      Order allow,deny
      Allow from all
     </Directory>
    
    </VirtualHost>
    
    
    上面的例子都使用 HTTP 协议进行通讯。如果加载合适的 mod_proxy 模块,您也可以使用 AJP 或 HTTPS 协议。详情请参考 http://httpd.apache.org/docs/2.2/mod/mod_proxy.html 里 Apache 的 mod_proxy 文档。
  4. 启用 Sticky Session。

    Sticky sessions 表示如果客户请求最开始是转到专有的 JBoss EAP 6 节点,所有以后的请求都将发送到相同的节点,除非这个节点不可用。这通常是正确的行为。
    要为 mod_proxy 启用 Sticky Session,请添加 stickysession 参数到 ProxyPass 语句里。这个例子也展示了一些其他的参数。更多信息请参考 Apache 的 mod_proxy 文档:http://httpd.apache.org/docs/2.2/mod/mod_proxy.html
    ProxyPass /MyApp balancer://mycluster stickysession=JSESSIONID lbmethod=bytraffic nofailover=Off
  5. 重启 HTTPD。

    重启 HTTPD 服务器以使修改生效。
结果

配置 HTTPD 使用 mod_proxy 以标准或负载平衡方式发送客户请求到 JBoss EAP 6 服务器或群集。要配置 JBoss EAP 6 响应这些请求,请参考 第 16.3.6 节 “配置 JBoss EAP 6 从外部 HTTPD 接受请求”

16.8. Microsoft ISAPI

16.8.1. 关于 Internet Server API (ISAPI) HTTP 连接器

Internet Server API (ISAPI) 是用于 Microsoft 的 Internet Information Services (IIS) Web 服务器的。您可以将 JBoss EAP 6 用作 IIS 群集里的一个工作节点。
要配置 JBoss EAP 6 参与 IIS 群集,请参考 第 16.8.2 节 “配置 Microsoft IIS 使用 ISAPI Redirector”。关于 ISAPI 的更多信息,请参考 http://msdn.microsoft.com/en-us/library/ms524911(v=VS.90).aspx

16.8.2. 配置 Microsoft IIS 使用 ISAPI Redirector

前提条件

  • 请确保使用受支持的操作系统并安装 IIS 服务器。关于受支持的配置列表,请参考 https://access.redhat.com/site/articles/111663
  • 从客户门户 https://access.redhat.com 下载用于 Microsoft Windows 的 JBoss Native 组件软件包。进入 Downloads - JBoss Enterprise Middleware - Application Platform。选择 i386x86_64。解压文件,其中包含了 jboss-eap-6.0/modules/native/sbin/ 里的 ISAPI Redirect DLL。
    解压 Native 组件压缩文件并复制 sbin\ 目录的内容到您选择的某个位置。本节剩下的部分将假设您使用了 C:\connectors\

过程 16.14. 用 IIS Manager (IIS 7) 配置 IIS Redirector

  1. 点击 StartRun 打开 IIS manager,然后输入 inetmgr
  2. 在左侧的树型视图面板里,展开 IIS 7
  3. 双击 ISAPI and CGI Registrations 在新窗口里打开它。
  4. Actions 面板里,点击 AddAdd ISAPI or CGI Restriction 窗口将会打开。
  5. 指定下列值:
    • ISAPI or CGI Path: c:\connectors\isapi_redirect.dll
    • Description: jboss
    • Allow extension path to execute:选择复选框。
  6. 点击 OK 来关闭Add ISAPI or CGI Restriction 窗口。
  7. 定义 JBoss Native 虚拟目录

    1. 右击 Default Web Site,然后点击 Add Virtual DirectoryAdd Virtual Directory 窗口将会出现。
    2. 指定下列值来添加虚拟目录:
      • Alias: jboss
      • Physical Path: C:\connectors\
    3. 点击 OK 保存并关闭 Add Virtual Directory 窗口。
  8. 定义 JBoss Native ISAPI 重定向过滤器

    1. 在树型视图面板里,展开 SitesDefault Web Site
    2. 双击 ISAPI FiltersISAPI Filters Features 视图将会出现。
    3. Actions 面板里,点击 AddAdd ISAPI Filter 窗口将会出现。
    4. Add ISAPI Filter 窗口里指定下列值:
      • Filter name: jboss
      • Executable: C:\connectors\isapi_redirect.dll
    5. 点击 OK 保存并关闭 Add ISAPI Filters 窗口。
  9. 启用 ISAPI-dll 处理程序

    1. 双击树型视图面板里的 IIS 7 条目。IIS 7 Home Features View 会被打开。
    2. 双击 Handler MappingsHandler Mappings Features View 将会出现。
    3. IIS 7 Home Features View 组合框里,选择 StateEnabled and Disabled Groups 里会出现 Handler Mappings
    4. 找到 ISAPI-dll。如果它位于 Disabled 组,右击并选择 Edit Feature Permissions
    5. 启用下列权限:
      • Read
      • Script
      • Execute
    6. 点击 OK 保存并关闭 Edit Feature Permissions 窗口。
概述

本节配置了一组 JBoss EAP 6 服务器接受来自 ISAPI Redirector 的请求。它没有包括对负载平衡和高可以性失效切换的配置。如果您需要这些功能,请参考 第 16.8.4 节 “配置 ISAPI Redirector 在多个 JBoss EAP 6 服务器间平衡客户请求”

这个是在 IIS 服务器上完成的,我们假定 JBoss EAP 6 已按照 第 16.3.6 节 “配置 JBoss EAP 6 从外部 HTTPD 接受请求” 进行了配置。

过程 16.15. 编辑属性文件和设置重定向

  1. 创建一个目录来存储日志、属性文件和锁文件。

    本过程剩余的部分将假定您在使用 C:\connectors\ 目录。如果您使用了不同的目录,请相应地修改这些说明。
  2. 创建 isapi_redirect.properties 文件。

    创建名为 C:\connectors\isapi_redirect.properties 的文件。复制下列内容到文件里。
    # Configuration file for the ISAPI Redirector
    # Extension uri definition
    extension_uri=/jboss/isapi_redirect.dll
    
    # Full path to the log file for the ISAPI Redirector
    log_file=c:\connectors\isapi_redirect.log
    
    # Log level (debug, info, warn, error or trace)
    # Use debug only testing phase, for production switch to info
    log_level=debug
    
    # Full path to the workers.properties file
    worker_file=c:\connectors\workers.properties
    
    # Full path to the uriworkermap.properties file
    worker_mount_file=c:\connectors\uriworkermap.properties
    
    #Full path to the rewrite.properties file 
    rewrite_rule_file=c:\connectors\rewrite.properties
    
    如果您不想使用 rewrite.properties 文件,请用 # 注释最后一行。详情请参考 步骤 5
  3. 创建 uriworkermap.properties 文件

    uriworkermap.properties 文件包含了部署的应用程序 URL 和处理请求的工作节点间的映射。下面的例子展示了这个文件的语法。请将您的 uriworkermap.properties 文件放入 C:\connectors\
    # images and css files for path /status are provided by worker01
    /status=worker01
    /images/*=worker01
    /css/*=worker01
    
    # Path /web-console is provided by worker02
    # IIS (customized) error page is used for http errors with number greater or equal to 400
    # css files are provided by worker01
    /web-console/*=worker02;use_server_errors=400
    /web-console/css/*=worker01
    
    # Example of exclusion from mapping, logo.gif won't be displayed  
    # !/web-console/images/logo.gif=*
    
    # Requests to /app-01 or /app-01/something will be routed to worker01
    /app-01|/*=worker01
    
    # Requests to /app-02 or /app-02/something will be routed to worker02
    /app-02|/*=worker02
    
  4. 创建 workers.properties 文件。

    workers.properties 文件包含工作标签和服务器实例间的映射定义。下面的示例文件展示了这个文件的语法。请将这个文件放入 C:\connectors\ 目录。
    # An entry that lists all the workers defined
    worker.list=worker01, worker02
    
    # Entries that define the host and port associated with these workers
    
    # First JBoss EAP 6 server definition, port 8009 is standard port for AJP in EAP 
    worker.worker01.host=127.0.0.1
    worker.worker01.port=8009
    worker.worker01.type=ajp13
    
    # Second JBoss EAP 6 server definition
    worker.worker02.host= 127.0.0.100
    worker.worker02.port=8009
    worker.worker02.type=ajp13
    
  5. 创建 rewrite.properties 文件。

    rewrite.properties 文件包含了专有应用程序的简单 URL 重写规则。如下例所示,重写路径使用名称-值对来指定的。请将这个文件放入 C:\connectors\ 目录。
    #Simple example
    # Images are accessible under abc path
    /app-01/abc/=/app-01/images/
    
  6. 重启 IIS 服务器。

    通过 net stopnet start 命令重启 IIS 服务器。
    C:\> net stop was /Y
    C:\> net start w3svc
    
结果

根据应用程序配置 IIS 服务器发送客户请求到专门的 JBoss EAP 6 服务器。

概述

这个配置将客户请求在多个 JBoss EAP 6 服务器间进行平衡。如果您希望将客户请求发送到专门的 JBoss EAP 6 服务器,请参考 第 16.8.3 节 “配置 ISAPI Redirector 发送客户请求到 JBoss EAP 6”

这个是在 IIS 服务器上完成的,我们假定 JBoss EAP 6 已按照 第 16.3.6 节 “配置 JBoss EAP 6 从外部 HTTPD 接受请求” 进行了配置。

过程 16.16. 在多个服务器间平衡客户请求

  1. 创建一个目录来存储日志、属性文件和锁文件。

    本过程剩余的部分将假定您在使用 C:\connectors\ 目录。如果您使用了不同的目录,请相应地修改这些说明。
  2. 创建 isapi_redirect.properties 文件。

    创建名为 C:\connectors\isapi_redirect.properties 的文件。复制下列内容到文件里。
    # Configuration file for the ISAPI Redirector
    # Extension uri definition
    extension_uri=C:\connectors\isapi_redirect.dll
    
    # Full path to the log file for the ISAPI Redirector
    log_file==c:\connectors\isapi_redirect.log
    
    # Log level (debug, info, warn, error or trace)
    # Use debug only testing phase, for production switch to info
    log_level=debug
    
    # Full path to the workers.properties file
    worker_file=c:\connectors\workers.properties
    
    # Full path to the uriworkermap.properties file
    worker_mount_file=c:\connectors\uriworkermap.properties
    
    #OPTIONAL: Full path to the rewrite.properties file 
    rewrite_rule_file=c:\connectors\rewrite.properties
    
    如果您不想使用 rewrite.properties 文件,请用 # 注释最后一行。详情请参考 步骤 5
  3. 创建 uriworkermap.properties 文件。

    uriworkermap.properties 文件包含了部署的应用程序 URL 和处理请求的工作节点间的映射。下面的例子展示了这个文件的语法及负载平衡配置。通配符(*)发送不同子目录的所有请求到负载平衡器 router步骤 4 里介绍了负载平衡器的配置。
    uriworkermap.properties 文件放入 C:\connectors\
    # images, css files, path /status and /web-console will be
    # provided by nodes defined in the load-balancer called "router"
    /css/*=router
    /images/*=router
    /status=router
    /web-console|/*=router
    
    # Example of exclusion from mapping, logo.gif won't be displayed  
    !/web-console/images/logo.gif=*
    
    # Requests to /app-01 and /app-02 will be routed to nodes defined
    # in the load-balancer called "router"
    /app-01|/*=router
    /app-02|/*=router
    
    # mapping for management console, nodes in cluster can be enabled or disabled here
    /jkmanager|/*=status
    
  4. 创建 workers.properties 文件。

    workers.properties 文件包含工作标签和服务器实例间的映射定义。下面的示例文件展示了这个文件的语法。负载平衡器是在文件的结尾进行配置的,由 worker01worker02 组成。workers.properties 文件遵循 Apache mod_jk 配置里使用的相同文件的语法。关于 workers.properties 文件语法的更多信息,请参考 第 16.6.5 节 “Apache Mod_jk 工作节点的配置”
    将这个文件放入 C:\connectors\ 目录。
    # The advanced router LB worker
    worker.list=router,status
    
    # First EAP server definition, port 8009 is standard port for AJP in EAP
    #
    # lbfactor defines how much the worker will be used. 
    # The higher the number, the more requests are served
    # lbfactor is useful when one machine is more powerful 
    # ping_mode=A – all possible probes will be used to determine that
    # connections are still working
    
    worker.worker01.port=8009
    worker.worker01.host=127.0.0.1
    worker.worker01.type=ajp13
    worker.worker01.ping_mode=A
    worker.worker01.socket_timeout=10
    worker.worker01.lbfactor=3
    
    # Second EAP server definition
    worker.worker02.port=8009
    worker.worker02.host= 127.0.0.100
    worker.worker02.type=ajp13
    worker.worker02.ping_mode=A
    worker.worker02.socket_timeout=10
    worker.worker02.lbfactor=1
    
    # Define the LB worker
    worker.router.type=lb
    worker.router.balance_workers=worker01,worker02
    
    # Define the status worker for jkmanager
    worker.status.type=status
    
  5. 创建 rewrite.properties 文件。

    rewrite.properties 文件包含了专有应用程序的简单 URL 重写规则。如下例所示,重写路径使用名称-值对来指定的。请将这个文件放入 C:\connectors\ 目录。
    #Simple example
    # Images are accessible under abc path
    /app-01/abc/=/app-01/images/
    
  6. 重启 IIS 服务器。

    通过 net stopnet start 命令重启 IIS 服务器。
    C:\> net stop was /Y
    C:\> net start w3svc
    
结果

配置 IIS 服务器发送客户请求到 workers.properties 文件里引用的 JBoss EAP 6 服务器,在服务器间均匀地调配负载。

16.9. Oracle NSAPI

16.9.1. 关于 Netscape Server API (NSAPI) HTTP 连接器

Netscape Server API (NSAPI) 是一个 HTTP 连接器,它允许 JBoss EAP 6 作为 Oracle iPlanet Web Server(以前的 Netscape Web Server)里的节点。要配置这个连接器,请参考 第 16.9.4 节 “配置 NSAPI 为负载平衡群集”

16.9.2. 在 Oracle Solaris 上配置 NSAPI Connector

概述

NSAPI connector 是一个运行在 Oracle iPlanet Web Server 内部的模块。

前提条件

  • 您的服务器在 32 或 64 位架构上运行 Oracle Solaris 10 或更高版本。
  • 除了 NSAPI connector 以外,对于 Intel 架构,安装和配置 Oracle iPlanet Web Server 7.0.15 或更高版本;对于 SPARC 架构,7.0.14 或更高版本。
  • 在每台将作为工作节点的服务器上安装和配置JBoss EAP 6。请参考 第 16.3.6 节 “配置 JBoss EAP 6 从外部 HTTPD 接受请求”
  • 从客户服务门户 https://access.redhat.com 下载 JBoss Native Components ZIP 软件包。

过程 16.17. 解压和设置 NSAPI Connector

  1. 解压 JBoss Native 组件软件包。

    本过程剩余的部分将假定 Native Components 软件包的 lib/lib64/ 被解压至 /opt/oracle/webserver7/config/ 里名为 connectors/ 的目录。这个目录将被称为 IPLANET_CONFIG。如果您的 Oracle iPlanet 配置目录是不同的,或者您运行的是 Oracle iPlanet Web Server 6,请相应地修改这个过程。
  2. 禁用 servlet 映射。

    打开 IPLANET_CONFIG/default.web.xml 文件并找到头部为 Built In Server Mappings 的部分。用注释字符(<!-- and -->)来禁用下列三个 Servlet 的映射。
    • default
    • invoker
    • jsp
    下面的配置示例展示了禁用的映射:
    <!-- ============== Built In Servlet Mappings =============== -->
    <!-- The servlet mappings for the built in servlets defined above. -->
    <!-- The mapping for the default servlet -->
    <!--servlet-mapping>
     <servlet-name>default</servlet-name>
     <url-pattern>/</url-pattern>
    </servlet-mapping-->
    <!-- The mapping for the invoker servlet -->
    <!--servlet-mapping>
     <servlet-name>invoker</servlet-name>
     <url-pattern>/servlet/*</url-pattern>
    </servlet-mapping-->
    <!-- The mapping for the JSP servlet -->
    <!--servlet-mapping>
     <servlet-name>jsp</servlet-name>
     <url-pattern>*.jsp</url-pattern>
    </servlet-mapping-->
    
    保存文件并退出。
  3. 配置 iPlanet Web Server 来加载 NSAPI connector 模块。

    添加下列行到 IPLANET_CONFIG/magnus.conf 文件的结尾,根据您的配置修改文件路径。这些行定义了 nsapi_redirector.so 模块和列出工作节点和属性的 workers.properties 文件的位置。
    Init fn="load-modules" funcs="jk_init,jk_service" shlib="IPLANET_CONFIG/connectors/lib/nsapi_redirector.so" shlib_flags="(global|now)"
    Init fn="jk_init" worker_file="IPLANET_CONFIG/connectors/workers.properties" log_level="debug" log_file="IPLANET_CONFIG/config/connectors/nsapi.log" shm_file="IPLANET_CONFIG/conf/connectors/jk_shm"
    
    上面的配置可用于 32 位系统。如果您使用 64 位的 Solaris,请将 lib/nsapi_redirector.so 修改为 lib64/nsapi_redirector.so
    保存文件并退出。
  4. 配置 NSAPI connector。

    您可以对 NSAPI connector 进行基本配置,不附带负载平衡。请在配置完成前选择下列选项。

16.9.3. 将 NSAPI 配置为 Basic HTTP Connector

概述

这个任务配置 NSAPI 连接器将客户请求转发到没由负载平衡或失效切换的 JBoss EAP 6 服务器。这个重定向是对每个部署(每个 URL)来进行的。关于负载平衡的配置,请参考 第 16.9.4 节 “配置 NSAPI 为负载平衡群集”

前提条件

过程 16.18. 设置 Basic HTTP Connector

  1. 定义重定向到 JBoss EAP 6 服务器的 URL 路径。

    注意

    IPLANET_CONFIG/obj.conf 里,行的开头不能有空格,除非是之前行的继续。
    编辑 IPLANET_CONFIG/obj.conf 文件。定位到以 <Object name="default"> 开始的部分,并按下例里展示的格式添加要匹配的每个 URL 模式。jknsapi 字符串引用下一个步骤里将定义的 HTTP 连接器。这个例子展示了使用通配符来进行模式匹配。
    <Object name="default">
    [...]
    NameTrans fn="assign-name" from="/status" name="jknsapi"
    NameTrans fn="assign-name" from="/images(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/css(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/nc(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/jmx-console(|/*)" name="jknsapi"
    </Object>
    
    
  2. 定义服务每个路径的工作节点。

    继续编辑 IPLANET_CONFIG/obj.conf 文件。在刚完成编辑部分的关闭标签(</Object>)后直接添加下列内容:
    <Object name="jknsapi">
    ObjectType fn=force-type type=text/plain
    Service fn="jk_service" worker="worker01" path="/status"
    Service fn="jk_service" worker="worker02" path="/nc(/*)"
    Service fn="jk_service" worker="worker01"
    </Object>
    
    
    上面的例子将发送到 URL 路径 /status 的请求重定向到名为 worker01 的节点,以及 /nc/ 下的所有 URL 路径重定向到 worker02 工作节点。第三行指定分配给 jknsapi 对象的所有不匹配前面两行的 URL 都转到 worker01
    保存文件并退出。
  3. 定义工作节点和属性。

    Create a file called workers.properties in the IPLANET_CONFIG/connectors/ directory. Paste the following contents into the file, and modify them to suit your environment.
    # An entry that lists all the workers defined
    worker.list=worker01, worker02
    
    # Entries that define the host and port associated with these workers
    worker.worker01.host=127.0.0.1
    worker.worker01.port=8009
    worker.worker01.type=ajp13
    
    worker.worker02.host=127.0.0.100
    worker.worker02.port=8009
    worker.worker02.type=ajp13
    
    workers.properties 文件使用和 Apache mod_jk 相同的语法。关于哪些选项可用的信息,请参考 第 16.6.5 节 “Apache Mod_jk 工作节点的配置”
    保存文件并退出。
  4. 重启 iPlanet Web Server。

    用下列命令来重启 iPlanet Web Server。
    IPLANET_CONFIG/../bin/stopserv
    IPLANET_CONFIG/../bin/startserv
    
结果

iPlanet Web Server 现在将发送到您已经配置的 URL 上的客户请求重定向到 JBoss EAP 6 上的部署。

16.9.4. 配置 NSAPI 为负载平衡群集

概述

这个任务配置 NSAPI 连接器将客户请求转发到负载平衡配置里的 JBoss EAP 6 服务器。要将 NSAPI 用作简单的不带负载平衡的 HTTP 连接器,请参考 第 16.9.3 节 “将 NSAPI 配置为 Basic HTTP Connector”

前提条件

过程 16.19. 为负载平衡配置连接器

  1. 定义重定向到 JBoss EAP 6 服务器的 URL 路径。

    注意

    IPLANET_CONFIG/obj.conf 里,行的开头不能有空格,除非是之前行的继续。
    编辑 IPLANET_CONFIG/obj.conf 文件。定位到以 <Object name="default"> 开始的部分,并按下例里展示的格式添加要匹配的每个 URL 模式。jknsapi 字符串引用下一个步骤里将定义的 HTTP 连接器。这个例子展示了使用通配符来进行模式匹配。
    <Object name="default">
    [...]
    NameTrans fn="assign-name" from="/status" name="jknsapi"
    NameTrans fn="assign-name" from="/images(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/css(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/nc(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/jmx-console(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/jkmanager/*" name="jknsapi"   
    </Object>
    
    
  2. 定义服务每个路径的工作节点。

    继续编辑 IPLANET_CONFIG/obj.conf 文件。在之前步骤里修改的内容(</Object>)的闭合标签之后添加下列内容并按需要进行修改:
    <Object name="jknsapi">
    ObjectType fn=force-type type=text/plain
    Service fn="jk_service" worker="status" path="/jkmanager(/*)"
    Service fn="jk_service" worker="router"
    </Object>	  
    
    
    这个 jksnapi 对象定义了用于服务映射到 default 对象里 name="jksnapi" 映射的每个路径的工作节点。除了映射 /jkmanager/* 的 URL 都被重定向到名为 router 的工作节点。
  3. 定义工作节点和属性。

    Create a file called workers.properties in IPLANET_CONFIG/connector/. Paste the following contents into the file, and modify them to suit your environment.
    # The advanced router LB worker
    # A list of each worker
    worker.list=router,status
    
    # First JBoss EAP server
    # (worker node) definition.
    # Port 8009 is the standard port for AJP
    #
    
    worker.worker01.port=8009
    worker.worker01.host=127.0.0.1
    worker.worker01.type=ajp13
    worker.worker01.ping_mode=A
    worker.worker01.socket_timeout=10
    worker.worker01.lbfactor=3
    
    # Second JBoss EAP server
    worker.worker02.port=8009
    worker.worker02.host=127.0.0.100
    worker.worker02.type=ajp13
    worker.worker02.ping_mode=A
    worker.worker02.socket_timeout=10
    worker.worker02.lbfactor=1
    
    # Define the load-balancer called "router"
    worker.router.type=lb
    worker.router.balance_workers=worker01,worker02
    
    # Define the status worker
    worker.status.type=status
    
    workers.properties 文件使用和 Apache mod_jk 相同的语法。关于哪些选项可用的信息,请参考 第 16.6.5 节 “Apache Mod_jk 工作节点的配置”
    保存文件并退出。
  4. 重启 iPlanet Web Server。

    根据您运行的是 iPlanet Web Server 6.1 还是 7.0,选择下列过程。
    • iPlanet Web Server 6.1

      IPLANET_CONFIG/../stop
      IPLANET_CONFIG/../start
      
    • iPlanet Web Server 7.0

      IPLANET_CONFIG/../bin/stopserv
      IPLANET_CONFIG/../bin/startserv
      
结果

iPlanet Web Server 将您配置的 URL 模式重定向到负载平衡配置里的 JBoss EAP 6 服务器。

第 17 章 消息系统

17.1. 简介

17.1.1. HornetQ

HornetQ 是红帽开发的多协议的异步消息系统。HornetQ 提供带有自动客户失效切换的高可用性(HA),保证了在服务器发生故障时消息的可靠性。HornetQ 也支持灵活的群集方案以平衡消息负载。
消息系统允许您将多种系统用更好的可靠性松散地耦合在一起。Java Messaging Service (JMS) 供应商使用事务系统来提交或回滚原子的修改。不像基于 Remote Procedure Call (RPC) 模式的系统,消息系统主要使用异步的消息传递模式,在请求和响应间没有紧密的关系。多数消息系统也支持请求-响应模式,但这不是消息系统的主要功能。
消息系统将消息的发送者和消费者分离。发送者和消费者是完全独立的,彼此完全不知晓对方。这允许您创建灵活的、松耦合的系统。通常,大型的企业使用消息系统来实现消息总线,将多种系统松散地耦合在一起。消息总线通常组成 Enterprise Service Bus (ESB) 的核心。使用消息总线来分离不同的系统允许系统更容易成长和适应。它也提供了增加系统、减少旧系统更大的灵活性,因为它们之间的依赖性较低。

17.1.3. 支持的消息风格

HornetQ 支持下列消息风格:
消息队列模式
消息队列模式涉及发送消息到队列里。消息位于队列后,它通常会被持久化以保证递送。一旦消息已经在队列里移动,消息系统会将其递送到某个消息消费者。进行处理后,消息消费者会确认递送。
当和点对点消息系统一起使用时,消息队列模式允许一个队列对应多个消费者,但每个消息只能被单个消费者接收。
发布-订阅模式
发布-订阅(Publish-Subscribe)模式允许多个发送者发送消息到服务器上的单个实体。这个实体通常被称为“主题(Topic)”。每个主题都可被多个消费者使用,称为“订阅(subscription)”。
每个订阅都接收发送到这个主题的每条消息的备份。这和消息队列模式不同,每条消息只能由单个消费者消费。
持久性的订阅保持发送到主题的每个消息的备份,直至订阅者消费这些消息。在服务器重启时这些备份也会保留。非持久性的订阅则和创建它们的连接持续的时间一致。
HornetQ 将连接器和接收器的概念作为消息系统的关键部分。

接收器和连接器

Acceptor
接收器(Acceptor)定义 HornetQ 服务器接受哪个类型的连接。
Connector
连接器(Connector)定义 HornetQ 客户如何使用它来连接 HornetQ 服务器。
根据配对的连接器和接收器是否处于相同的 JVM,有两种类型的连接器和接收器。

Invm 和 Netty

Invm
Invm 是 Intra Virtual Machine 的简称。当客户和服务器运行在同一个 JVM 里时可以使用它。
Netty
JBoss 项目的名称。当客户和服务器运行在不同的 JVM 里时必须使用它。
HornetQ 客户必须使用兼容其中一个服务接收器的连接器。只有 Invm 连接器可以连接 Invm 接收器,也只有 netty 连接器可以连接 netty 接收器。连接器和接收器都可以在服务器的 standalone.xmldomain.xml 里进行配置。您可以使用管理控制台或管理 CLI 来定义它们。

例 17.1. 默认的接收器和连接器配置示例

<connectors>
    <netty-connector name="netty" socket-binding="messaging"/>
    <netty-connector name="netty-throughput" socket-binding="messaging-throughput">
        <param key="batch-delay" value="50"/>
    </netty-connector>
    <in-vm-connector name="in-vm" server-id="0"/>
</connectors>
<acceptors>
    <netty-acceptor name="netty" socket-binding="messaging"/>
    <netty-acceptor name="netty-throughput" socket-binding="messaging-throughput">
        <param key="batch-delay" value="50"/>
        <param key="direct-deliver" value="false"/>
    </netty-acceptor>
    <in-vm-acceptor name="in-vm" server-id="0"/>
</acceptors>

配置示例也展示了 HornetQ 的 JBoss EAP 6 实现在接收器和连接器配置里是如何使用套接字绑定的。这和 HornetQ 的独立版本不同,它要求声明专门的主机和端口。

17.3. 关于消息桥(Bridge)

桥的功能是从源队列消费消息,并将其转发到通常位于不同 HornetQ 服务器上的目标地址。桥处理不可靠的连接,当连接再次可用时自动重连。HornetQ 桥可以用过滤器表达式进行配置,只转发某些消息。
Java Naming and Directory Interface (JNDI) 是一个用于命名和目录服务的标准的 Java API。它允许用基于 Java 的技术来发现和组织分布式计算环境里的命名组件。

17.5. 处理大型消息

即使客户端或服务器的内存有限,HornetQ 也支持大型消息。大型消息可以流化(streamed)或进行压缩以更高效地传输。

17.6. 配置

17.6.1. 配置 JMS 服务器

要为 HornetQ 配置 JMS 服务器,请编辑服务器配置文件。对于域服务器,服务器配置包含在 EAP_HOME/domain/configuration/domain.xml 里;而对于独立服务器,则位于 EAP_HOME/standalone/configuration/standalone.xml 文件里。
<subsystem xmlns="urn:jboss:domain:messaging:1.3"> 元素包含了所有的 JMS 配置。按需要为 JNDI 添加任何 JMS ConnectionFactoryQueueTopic 实例。
  1. 启用 JBoss EAP 6 里的 JMS 子系统。

    <extensions> 元素里,检查是否有下面一行且没被注释:
    <extension module="org.jboss.as.messaging"/>
  2. 添加基本的 JMS 子系统。

    如果 Messaging 子系统没有出现在你的配置文件里,请添加它。
    1. 查找对应你所使用的配置集的 <profile>,并定位它的 <subsystems> 标签。
    2. <subsystems> 标签下添加一新行,并粘贴下列内容:
      <subsystem xmlns="urn:jboss:domain:messaging:1.3">
      
      </subsystem>
      
      所有进一步的配置都将添加到空行的上方。
  3. 添加基本的 JMS 配置。

    <journal-file-size>102400</journal-file-size>
    <journal-min-files>2</journal-min-files>
    <journal-type>NIO</journal-type>
    <!-- disable messaging persistence -->
    <persistence-enabled>false</persistence-enabled>
    
    定制上面的值以满足你的需要。

    警告

    journal-file-size 的值必须比发往服务器的消息大小要大,否则服务器无法存储这个消息。
  4. 在 HornetQ 里添加连接工厂实例

    客户使用 JMS ConnectionFactory 对象来创建到服务器的连接。要添加 JMS 连接工厂对象到 HornetQ 里,请为每个连接工厂包含一个 <jms-connection-factories> 标签和 <connection-factory> 元素:
    <subsystem xmlns="urn:jboss:domain:messaging:1.3">
      ...
      <jms-connection-factories>
        <connection-factory name="myConnectionFactory">
          <connectors>
            <connector-ref connector-name="netty"/>
          </connectors>
          <entries>
            <entry name="/ConnectionFactory"/>           
          </entries>
        </connection-factory>
      </jms-connection-factories>
      ...
    </subsystem>
    
  5. 配置 netty 连接器

    这个 JMS 连接工厂使用一个 netty 连接器。这是一个对部署在服务器配置文件里的连接器对象的引用。这个连接器对象定义了实际用来连接服务器的传输协议和参数。
    要配置 netty 连接器,请包含下列设置:
    <subsystem xmlns="urn:jboss:domain:messaging:1.3">
      ...
      <connectors>
        <netty-connector name="netty" socket-binding="messaging"/>
        <netty-connector name="netty-throughput" socket-binding="messaging-throughput">
          <param key="batch-delay" value="50"/>
        </netty-connector>
        <in-vm-connector name="in-vm" server-id="0"/>
      </connectors>
      ...
    </subsystem>
    
    这个连接器引用了 messagingmessaging-throughput 套接字绑定。messaging 套接字绑定使用端口 5445,而 messaging-throughput 套接字绑定使用端口 5455。 请确保下列套接字绑定出现在 <socket-binding-groups> 元素里:
    <socket-binding-groups>
      ...
      <socket-binding-group ... >
        <socket-binding name="messaging" port="5445"/>
        <socket-binding name="messaging-throughput" port="5455"/>
        ...
      </socket-binding-group>
      ...
    </socket-binding-groups>
    
  6. 可选:添加 queue 实例到 HornetQ 里

    有四种方法可设置 HornetQ 的队列实例(或 JMS 目的地)。
    • 使用管理控制台
      要使用管理控制台,服务器必须已经以 Message-Enabled 模式启动。您可以用 -c 选项并强制使用 standalone-full.xml(对于独立服务器)配置文件来做到这一点。例如,在独立模式下,下列命令将以 message-enabled 模式启动服务器:
      ./standalone.sh -c standalone-full.xml
      服务器启动后,登录管理控制台并导航至:Profile → Messaging → Destinations → default → View,然后点击 Add 按钮来输入 JMS 目的地的细节。
    • 使用管理 CLI:
      首先,连接至管理 CLI:
       bin/jboss-cli.sh --connect
      然后,进入消息子系统:
      cd /subsystem=messaging/hornetq-server=default
      最后,执行 add 操作,用自己的内容替换下例里的值:
      ./jms-queue=testQueue:add(durable=false,entries=["java:jboss/exported/jms/queue/test"])
    • 创建一个 JMS 配置文件并将其添加至 deployments 文件夹
      从创建 JMS 配置文件 example-jms.xml 开始。添加下列条目,用自己的设置替换相关的值:
      <?xml version="1.0" encoding="UTF-8"?>				  	  <messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
          <hornetq-server>
              <jms-destinations>
                  <jms-queue name="testQueue">
                      <entry name="queue/test"/>
                      <entry name="java:jboss/exported/jms/queue/test"/>
                  </jms-queue>
                  <jms-topic name="testTopic">
                      <entry name="topic/test"/>
                      <entry name="java:jboss/exported/jms/topic/test"/>
                  </jms-topic>
              </jms-destinations>
          </hornetq-server>
      </messaging-deployment>
      
      保存文件到 deployments 文件夹并进行部署。
    • 在 JBoss EAP 6 配置文件里添加条目。
      standalone-full.xml 为例子,找到里面的消息子系统。
      <subsystem xmlns="urn:jboss:domain:messaging:1.3">
      
      添加下列条目,并用自己的设置替换相关的值。您需要在 </jms-connection-factories> 标签后但在 </hornetq-server> 元素前添加这些内容:
      <jms-destinations>
              <jms-queue name="testQueue">
                  <entry name="queue/test"/>
                  <entry name="java:jboss/exported/jms/queue/test"/>
              </jms-queue>
              <jms-topic name="testTopic">
                  <entry name="topic/test"/>
                  <entry name="java:jboss/exported/jms/topic/test"/>
              </jms-topic>
          </jms-destinations>
      
  7. 执行其他的配置

    如果您需要其他的设置,请复查 EAP_HOME/docs/schema/jboss-messaging_1_3.xsd 里的 DTD。

17.6.2. 配置 JMS 地址设置

JMS 子系统有几个可配置选项,它们控制消息如何和何时递送、可以多少次重试、何时过期。这些配置选项都存在于 <address-settings> 配置元素里。
地址配置的一个常见功能是映射多个地址的语法,也称作通配符。
通配符语法

地址通配符可用来映射多个类似的地址到单个语句,就像多个系统使用星号( *)字符来映射多个文件或字符串。下面的字符在通配符语句里都有特定的含义。

Expand
表 17.1. JMS 通配符语法
字符 描述
. (单个句号) 表示通配符表达式里单词间的空格。
# (井字键) 匹配零或多个单词的任意序列。
* (星号) 匹配单个单词。
Expand
表 17.2. JMS 通配符示例
示例 描述
news.europe.#
匹配 news.europenews.europe.sportnews.europe.politic,但不匹配 news.usaeurope
news.
匹配 news.europe 但不匹配 news.europe.sport
news.*.sport
匹配 news.europe.sportnews.usa.sport 但不匹配 news.europe.politics

例 17.2. 默认的地址设置配置

这个例子里的值适用于本节的剩余内容。
<address-settings>
    <!--default for catch all-->
    <address-setting match="#">
        <dead-letter-address>jms.queue.DLQ</dead-letter-address>
        <expiry-address>jms.queue.ExpiryQueue</expiry-address>
        <redelivery-delay>0</redelivery-delay>
        <max-size-bytes>10485760</max-size-bytes>
        <address-full-policy>BLOCK</address-full-policy>
        <message-counter-history-day-limit>10</message-counter-history-day-limit>
    </address-setting>
</address-settings>

Expand
表 17.3. JMS 地址设置的描述
元素 描述 默认值 类型
address-full-policy
确定当已指定 max-size-bytes 的地址已满时发生的事情。
PAGE
STRING
dead-letter-address
如果指定了 Dead Letter 地址,如果 max-delivery-attempts 次递送尝试已失败,消息会移动到这个地址。否则,未递送的消息将被舍弃。这里允许使用通配符。
jms.queue.DLQ
STRING
expiry-address
如果指定了过期地址,过期的消息将被送到这个地址或匹配的地址,而不会被舍弃。这里允许使用通配符。
jms.queue.ExpiryQueue
STRING
last-value-queue
定义队列是否只使用最后的值。
false
BOOLEAN
max-delivery-attempts
在消息被发送到 dead-letter-address 或舍弃前重新递送的最多次数。
10
INT
max-size-bytes
最大值(字节)。
10485760L
LONG
message-counter-history-day-limit
消息计数器历史的每日限制。
10
INT
page-max-cache-size
在页面导航过程中保持在内存里以优化 IO 的页面文件的数量。
5
INT
page-size-bytes
页面大小。
5
INT
redelivery-delay
在重新递送消息间延迟的时间,单位为毫秒。如果为 0,重递送将无限期进行下去。
0L
LONG
redistribution-delay
当队列上最后一个消费者关闭时重新发布任何消息前等待的时间。
-1L
LONG
send-to-dla-on-no-route
设置消息不路由至任何队列而发送至 Dead Letter 地址(DLA)的条件的参数。
false
BOOLEAN
  • 配置地址设置和模式属性

    选择管理 CLI 或管理控制台来配置您的模式属性。
    • 用管理 CLI 配置地址设置

      使用管理 CLI 配置地址设置。
      1. 添加新的模式

        如果有需要,请使用 add 操作来创建新的地址设置。您可以在管理 CLI 会话的根目录里运行这个命令,下面的例子创建了一个名为 patternname 的模式,它的 max-delivery-attempts 属性声明为 5。下面展示了对独立服务器和受管域的 full 配置集的编辑。
        [domain@localhost:9999 /] /profile=full/subsystem=messaging/hornetq-server=default/address-setting=patternname/:add(max-delivery-attempts=5)
        [standalone@localhost:9999 /] /subsystem=messaging/hornetq-server=default/address-setting=patternname/:add(max-delivery-attempts=5)
      2. 编辑模式属性

        使用 write 操作来编写新的属性的值。您可以使用 tab completion 来帮助输入并提示所有可用的值。下面的例子将 max-delivery-attempts 的值更新为 10
        [domain@localhost:9999 /] /profile=full/subsystem=messaging/hornetq-server=default/address-setting=patternname/:write-attribute(name=max-delivery-attempts,value=10)
        [standalone@localhost:9999 /] /subsystem=messaging/hornetq-server=default/address-setting=patternname/:write-attribute(name=max-delivery-attempts,value=10)
      3. 确认模式属性

        使用 read-resource 操作和 include-runtime=true 参数来开放服务器模型里当前活动的所有值,确认值已被修改。
        [domain@localhost:9999 /] /profile=full/subsystem=messaging/hornetq-server=default/address-setting=patternname/:read-resource
        [standalone@localhost:9999 /] /subsystem=messaging/hornetq-server=default/address-setting=patternname/:read-resource
    • 用管理控制台配置地址设置

      使用管理控制台配置地址设置。
      1. 登录到管理控制台。

        登录至受管域或独立服务器的管理控制台。
      2. 如果您使用受管域,请选择正确的配置集。

        选择右上角的 Profiles 标签,然后从下一屏幕左上角的 Profile 菜单里选择正确的配置集。只有 fullfull-ha 配置集启用了 messaging 子系统。
      3. 从导航菜单里选择 Messaging 条目。

        从导航菜单里展开 Messaging 菜单并点击 Destinations
      4. 查看 JMS 供应商。

        JMS 供应商列表将会出现。在 default 配置里只有一个供应商,就是default。点击 View 链接查看这个供应商的详细设置。
      5. 查看地址设置。

        点击 Addressing 标签页。点击 Add 按钮添加新模式,或者点击已有名称及 Edit 按钮进行编辑。
      6. 配置选项。

        如果您在添加新的模式,Pattern 字段引用 address-setting 元素的 match 参数。您也可以编辑e Dead Letter Address, Expiry Address, Redelivery DelayMax Delivery Attempts。其他选项需要用管理 CLI 进行配置。

17.6.3. 用 HornetQ 配置消息系统

我们推荐在 JBoss EAP 6 里配置消息系统的方法是通过管理控制台或管理 CLI。你可以用这些工具来进行持久性的修改而无需手动编辑 standalone.xmldomain.xml 文件。但熟悉默认配置文件的消息组件是有用处的,而使用管理工具的示例的文档里包含了配置文件的片段以供参考。

17.6.4. 配置延迟的重递送

简介

延迟的重递送是在 <redelivery-delay> 元素里定义的,它是 JMS 子系统配置的 <address-setting> 元素的子元素。

<!-- delay redelivery of messages for 5s -->
<address-setting match="jms.queue.exampleQueue">
  <redelivery-delay>5000</redelivery-delay>
</address-setting>
如果指定了重递送时间,JMS 系统在重新递送这些消息前将等待。如果 <redelivery-delay> 被设置为 0,将不会发送重递送。地址通配符可以用在 <address-setting-match> 元素里来配置匹配通配符的地址的重递送延迟。

17.6.5. 配置 Dead Letter 地址

简介

Dead Letter 地址是在 JMS 子系统配置的 <address-setting> 元素里定义的。

<!-- undelivered messages in exampleQueue will be sent to the dead letter address 
deadLetterQueue after 3 unsuccessful delivery attempts
-->
<address-setting match="jms.queue.exampleQueue">
  <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
  <max-delivery-attempts>3</max-delivery-attempts>
</address-setting>
如果没有指定 <dead-letter-address>,消息在试图递送 <max-delivery-attempts> 次后将被删除。在默认情况下,消息会尝试递送 10 次。设置 <max-delivery-attempts>-1 会无限期地进行重递送。例如,对于一系列匹配的地址可以设置一个全局 Dead letter,而且对于专有的地址设置可以将 <max-delivery-attempts> 设置为 -1 来允许无限期的重递送到这个地址。地址通配符也可以用来配置一系列地址的 Dead Letter 设置。

17.6.6. 配置消息过期地址

简介

消息过期地址是在 JMS 的 address-setting 配置里定义的。例如:

<!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue -->
<address-setting match="jms.queue.exampleQueue">
  <expiry-address>jms.queue.expiryQueue</expiry-address>
</address-setting>
如果消息已过期且没有指定过期地址,消息将从队列里删除并丢弃。地址通配符(Address wildcards)也可以用来配置一系列地址的过期地址范围。
地址通配符

地址通配符可用来映射多个类似的地址到单个语句,就像多个系统使用星号(*)字符来映射多个文件或字符串。下面的字符在通配符语句里都有特定的含义。

Expand
表 17.4. JMS 通配符语法
字符 描述
. (单个句号) 表示通配符表达式里单词间的空格。
# (井字键) 匹配零或多个单词的任意序列。
* (星号) 匹配单个单词。
Expand
表 17.5. JMS 通配符示例
示例 描述
news.europe.#
匹配 news.europenews.europe.sportnews.europe.politic,但不匹配 news.usaeurope
news.
匹配 news.europe 但不匹配 news.europe.sport
news.*.sport
匹配 news.europe.sportnews.usa.sport 但不匹配 news.europe.politics

17.6.7. 对 HornetQ 配置属性的引用

HornetQ 的 JBoss EAP 6 实现开放了下列可配置的属性。你可以使用管理 CLI 通过 read-resource 操作开放可配置或可查看的属性。

例 17.3. 示例

[standalone@localhost:9999 /] /subsystem=messaging/hornetq-server=default:read-resource
Expand
表 17.6. HornetQ 属性
属性 示例值 类型
allow-failback true BOOLEAN
async-connection-execution-enabled true BOOLEAN
backup false BOOLEAN
cluster-password somethingsecure STRING
mask-password true BOOLEAN
cluster-user HORNETQ.CLUSTER.ADMIN.USER STRING
clustered false BOOLEAN
connection-ttl-override -1 LONG
create-bindings-dir true BOOLEAN
create-journal-dir true BOOLEAN
failback-delay 5000 LONG
failover-on-shutdown false BOOLEAN
id-cache-size 2000 INT
jmx-domain org.hornetq STRING
jmx-management-enabled false BOOLEAN
journal-buffer-size 100 LONG
journal-buffer-timeout 100 LONG
journal-compact-min-files 10 INT
journal-compact-percentage 30 INT
journal-file-size 102400 LONG
journal-max-io 1 INT
journal-min-files 2 INT
journal-sync-non-transactional true BOOLEAN
journal-sync-transactional true BOOLEAN
journal-type ASYNCIO STRING
live-connector-ref reference STRING
log-journal-write-rate false BOOLEAN
management-address jms.queue.hornetq.management STRING
management-notification-address hornetq.notifications STRING
memory-measure-interval -1 LONG
memory-warning-threshold 25 INT
message-counter-enabled false BOOLEAN
message-counter-max-day-history 10 INT
message-counter-sample-period 10000 LONG
message-expiry-scan-period 30000 LONG
message-expiry-thread-priority 3 INT
page-max-concurrent-io 5 INT
perf-blast-pages -1 INT
persist-delivery-count-before-delivery false BOOLEAN
persist-id-cache true BOOLEAN
persistence-enabled true BOOLEAN
remoting-interceptors undefined LIST
run-sync-speed-test false BOOLEAN
scheduled-thread-pool-max-size 5 INT
security-domain other STRING
security-enabled true BOOLEAN
security-invalidation-interval 10000 LONG
server-dump-interval -1 LONG
shared-store true BOOLEAN
started true BOOLEAN
thread-pool-max-size 30 INT
transaction-timeout 300000 LONG
transaction-timeout-scan-period 1000 LONG
version 2.2.16.Final (HQ_2_2_16_FINAL, 122) STRING
wild-card-routing-enabled true BOOLEAN

警告

journal-file-size 的值必须比发往服务器的消息大小要大,否则服务器无法存储这个消息。

17.6.8. 设置消息过期

简介

通过 HornetQ Core API,过期时间可以直接在消息上设置。例如:

// message will expire in 5000ms from now
message.setExpiration(System.currentTimeMillis() + 5000);
JMS MessageProducer

JMS MessageProducer 包含了一个 TimeToLive 参数,它控制发送的消息的过期:

// messages sent by this producer will be retained for 5s (5000ms) before expiration           
producer.setTimeToLive(5000);
从过期地址消费的过期消息具有下列属性:
  • _HQ_ORIG_ADDRESS
包含过期消息的原始地址的字符串型属性
  • _HQ_ACTUAL_EXPIRY
包含过期消息的实际过期时间的长整型属性。

17.7. 持久化

17.7.1. 关于 HornetQ 里的持久化

HornetQ 处理自己的持久化。它附带为专有消息用例进行了优化的高性能日志。
HornetQ 日志只使用可配置的文件大小进行附加,它通过单个写入操作来提高性能。它包含一系列文件,开始时都以固定大小预先创建并填充空白内容。当执行服务器操作(add message、delete message、update message 等)时,操作记录会附加到日志后面,直至日志文件已满,此时将使用下一个日志文件。
复杂的垃圾收集算法确定日志文件在所有数据被删除后是否被回收并重用。压缩算法将从日志文件删除无效空间并压缩数据。
日志也完全支持本地和 XA 事务。
日志的主要部分是用 Java 编写的,但和文件系统的交互已经抽象化为不同的可插入实现。HornetQ 附带的两个实现是:
  • Java New I/O (NIO)
    使用标准的 Java NIO 与文件系统交互。这提供了极佳的性能且可以运行在任何装有 Java 6 或更高版本的平台上。
  • Linux Asynchronous IO (AIO)
    使用 Native Code Wrapper 和 Linux Asynchronous IO Library(AIO)进行交互。通过 AIO,HornetQ 在数据已被持久化时接收消息。这避免了对显性同步的需要。AIO 通常会提供比 Java NIO 更好的性能,但它要求 Linux kernel 2.6 或更高的版本以及 libaio 软件包。
    AIO 也要求 ext2、ext3、ext4、jfs 或 xfs 文件系统。
标准的 HornetQ 核心服务器使用下列日志实例:
  • bindings journal
    存储和绑定相关的数据,包括部署在服务器上的队列及其属性。它也存储 ID 序列计数器等数据。绑定日志总是 NIO 日志,因为和消息日志相比它通常具有较低的吞吐量。
    这个日志里的文件的前缀是 hornetq-bindings。每个文件都有一个绑定扩展名。文件大小是1048576 字节,它位于 bindings 文件夹里。
  • JMS journal
    存储所有和 JMS 相关的数据,如任何 JMS 队列、主题或连接工厂以及用于这些资源的 JNDI 绑定。用管理 API 创建的任何 JMS 资源都保存在这个日志里,而用配置文件配置的资源则不会。这个日志只有在使用 JMS 时才会被创建。
  • message journal
    存储所有和消息相关的数据,包括消息本身及 duplicate-id 缓存。在默认情况下,HornetQ 将 AIO 用于这个日志。如果 AIO 不可用,它将自动退回为 NIO。
大型消息是在消息日志之外持久化的。在内存低的环境里,可以配置 HornetQ 将消息页面化到磁盘上。如果不需要持久化,可以配置 HornetQ 不持久化任何数据。

17.8. 高可用性

17.8.1. 关于 HornetQ 共享存储

在使用共享存储时,在线和备份服务器都用共享文件系统共享相同的整个数据目录。这包含 paging 目录、journal 目录、大型消息和绑定日志。当失效切换发生时,备份服务器开始接管,它将从共享文件系统加载持久性存储。然后客户可以进行连接。

重要

HornetQ 支持两种不同的共享存储配置:
  • SAN 上的 GFS2,使用 ASYNCIO 日志类型。
  • NFSv4,使用 ASYNCIO 或 NIO 日志类型。

重要

HornetQ 支持 NFS,但有着严格的配置准则,如下所示。
这种高可用性和数据复制不同,因为它要求有一个共享的文件系统供在线和备份节点访问。这通常是某种形式的高性能存储区域网络(Storage Area Network,SAN)。
红帽企业版 Linux NFS 实现支持直接 I/O(设置 O_DIRECT 标记并打开文件)以及基于内核的异步 I/O。使用这些功能,依据严格的配置规则,你可以将 NFS 做为一个共享存储选项使用。
  • 您必须配置 HornetQ 使用下列日志类型之一:ASYNCIO/AIO 或 NIO。
  • 红帽企业版 Linux NFS 客户缓存必须被禁用。

重要

你应该在 JBoss EAP 6 启动后检查服务器日志,以确保成功加载原生库且使用 ASYNCIO 日志类型。如果原生库加载失败,HornetQ 将使用 NIO 日志类型并在服务器日志里注明。

重要

实现异步 I/O 的 Native 库要求 libaio 安装在 JBoss EAP 6 运行的 Red Hat 企业版 Linux 系统上。

注意

我们推荐如果根据上面的条件使用 NFS,需要使用高可用的 NFS 配置。
共享存储高可用性的优势是在在线和备份节点间不需要进行复制。这意味着在正常操作时它不会有任何因为复制引起的性能损失。
共享存储的缺点是它要求一个共享文件系统,当备份服务器激活时,它需要从共享存储加载日志。根据存储里数据的多少,这会花费一些时间。
如果在普通操作时追求最高性能,且可以接受对快速 SAN 的访问及稍慢的失效切换速度(根据数据的多少),我们就会推荐高可用性的共享存储。

17.8.2. 关于高可用性(HA)失效切换

高可用性失效切换分为自动客户失效切换和使用在线-备份结构的应用程序级别的失效切换。每个在线服务器都有一个备份服务器,如果有需要也可以有多个备份服务器。
只有在线服务器崩溃时备份服务器才会接管。同时第二级备份服务器中的一个会接管成为被动备份服务器。在失效切换后且之前的在线服务器已经重启后,它会变成第二级的备份服务器,或者在只有两个服务器的情况下变成备份服务器。

重要

即使您没有使用群集功能,群集也应该启用。这是因为 HA 群集的每个节点都必须有一个到其他节点的群集连接,从而能够和其他服务器协商角色。

重要

共享的文件系统目录是必需的,目的是让备份服务器发送/接收消息,作为对之前在线服务器接收到的消息的回应。
在线和备份服务器实现了高可用性群集拓扑结构,它们使用 IP 多点传送发送连接细节。如果无法使用 IP 多点传送,也可能使用初始连接的静态配置。在初始连接之后,系统会将这个拓扑结构通知客户。如果当前的连接是稳定的,客户将和另外一个节点建立新的连接。

17.8.3. HornetQ 备份服务器上的部署

在指定的 HA 环境里,将 HornetQ 配置为备份服务器的 JBoss EAP 6 服务器不能用于运行任何使用或连接 HornetQ 备份服务器的部署。这包括 EJB(Stateless Session Beans、Message Driven Beans)或 Servlet。
如果 JBoss EAP 6 服务器具有 HornetQ 备份配置(消息子系统里配置为 'live' 而另外一个 HornetQ 服务器配置为 'backup'),JBoss EAP 6 服务器可以运行部署,只要这些部署是配置程连接 'live' HornetQ 服务器的。

17.9. 消息复制

17.9.1. HornetQ 消息复制

HornetQ 支持在一个或多个服务器发生故障后继续运行。这种功能部分是通过失效切换实现的,客户在在线服务器发生故障时从在线服务器移植到备份服务器。要保持备份服务器更新,消息持续地通过两个策略从在线服务器复制到备份服务器:共享存储(shared store)和复制(replication )。本节将涵盖复制策略。

警告

只有持久性消息才会被复制。非持久性消息无法通过失效切换保留。
当在线服务器和备份服务器不共享相同的数据存储时,它们之间的消息复制是通过网络实现的。所有的日志都在两个服务器间进行复制,只要这两个服务器位于相同的群集里且使用相同的群集用户名和密码。在线服务器接收的所有(持久性的)数据流量都会复制到备份服务器上。
当备份服务器在线时,它会查找并连接在线服务器以试图进行同步。在它进行同步时,它无法作为备份服务器访问。取决于要同步的数据的大小及网络速度,同步可能需要较长的时间。
备份服务器如何查找在线服务器并复制数据取决于 hornetq-configuration.xml 文件里是否已定义 backup-group-name 参数。备份服务器只能连接共享相同组名的在线服务器。未指定这个参数时,备份服务器将试图连接任何在线服务器。
在在线服务器发生故障的情况下,正确配置和同步的备份服务器将接管其职责。备份服务器将在在线服务器发生故障且无法连接却又可以连接群集里一半以上的服务器时运行。如果多过半数的服务器无法响应,它将指示网络错误,备份服务器将等待到在线服务器的连接重试。

17.9.2. 配置 HornetQ 服务器的复制

要配置在线和备份服务器为复制配对,请配置两者的 hornetq-configuration.xml 文件为:
<shared-store>false</shared-store>
.
.
.
<cluster-connections>
   <cluster-connection name="my-cluster">
      ...
   </cluster-connection>
</cluster-connections>
备份服务器也必须显性地标记。
<backup>true</backup>
<connectors>
   <connector name="nameOfConfiguredLiveServerConnector">
      <factory-class>
         org.hornetq.core.remoting.impl.netty.NettyConnectorFactory
      </factory-class>
   <param key="port" value="5445"/>
   </connector>
<!-- a real configuration could have more connectors here -->
<connectors>

第 18 章 事务子系统

18.1. 事务子系统的配置

18.1.2. 配置事务管理者

您可以使用基于 Web 的管理控制台或命令行管理 CLI 来配置事务管理者(Transaction Manager,TM)。对于每条命令或选项,我们都假设您在受管域里运行 JBoss EAP 6。如果您使用的是独立服务器或者您想使用 default 之外的配置集,您可能需要修改下面的步骤和命令。

命令示例注记

  • 在管理控制台里,第一次登录时会自动选择 default 配置集。如果您想改动到其他配置集,请选择其他配置集。
    类似地,请在 CLI 命令示例里替换 default 配置集。
  • 如果您使用的是独立服务器,则只存在一个配置集。请忽略选择配置集的说明。在 CLI 命令示例里,请删除 /profile=default 部分。

注意

为了使 TM 选项在管理控制台或管理 CLI 里可见,您必须启用 transactions。它默认是启用的,对于许多其他子系统的正常运行,它也是必需的,所以不太可能禁用它。
用管理控制台配置事务管理者

要使用基于 Web 的管理控制台配置 TM,请从管理控制台屏幕的左上角选择 Runtime 标签页。如果您使用受管域,您可以选择不同的配置集。从 Profiles 屏幕的右上角的 Profile 选择框里选择配置集。展开 Container 菜单并选择 Transactions

事务管理者配置页面里显示了多数的选项。Recovery 选项默认是隐藏的。点击 Recovery 头部展开它。然后点击 Edit 按钮来编辑任何选项。修改会立即生效。
点击 Need Help? 标签显示在线帮助文本。
用管理 CLI 配置事务管理者

在管理 CLI 里,您可以使用一系列命令来配置事务管理者。对于使用 default 的受管域,这些命令都以 /profile=default/subsystem=transactions/ 开始,而对于独立服务器则使用 /subsystem=transactions

Expand
表 18.1. 事务管理者配置选项
选项 描述 CLI 命令
启用统计
是否启用事务统计。这些统计可以在管理控制台的 Runtime 标签页里的 Subsystem Metrics 部分查看。
/profile=default/subsystem=transactions/:write-attribute(name=enable-statistics,value=true)
默认超时时间
默认的事务超时时间。默认值是 300 秒。您可以在程序里对每个事务覆盖这个值。
/profile=default/subsystem=transactions/:write-attribute(name=default-timeout,value=300)
路径
事务管理者核心存储数据的相对或绝对路径。默认值是相对于 relative-to 属性的相对路径。这个路径用来保存使用 process-id 标签(或 process-id-uuid CLI attribute)时的进程 ID。
/profile=default/subsystem=transactions/:write-attribute(name=path,value=var)
相对于
引用域模型里的全局路径配置。默认值是 JBoss EAP 6 的数据目录,即 jboss.server.data.dir 属性的值。对于受管域,默认是 EAP_HOME/domain/data/,而对于独立服务器是 EAP_HOME/standalone/data/path TM 属性是相对于这个路径的值。
/profile=default/subsystem=transactions/:write-attribute(name=relative-to,value=jboss.server.data.dir)
对象库路径
TM 对象库存储数据的相对或绝对文件系统路径。默认是相对于 object-store-relative-to 参数的路径。
/profile=default/subsystem=transactions/:write-attribute(name=object-store-path,value=tx-object-store)
对象库的相对路径
引用域模型里的全局路径配置。默认值是 JBoss EAP 6 的数据目录,即 jboss.server.data.dir 属性的值。对于受管域,默认是 EAP_HOME/domain/data/,而对于独立服务器是 EAP_HOME/standalone/data/。对象库的 path TM 属性是相对于这个路径的值。
/profile=default/subsystem=transactions/:write-attribute(name=object-store-relative-to,value=jboss.server.data.dir)
Socket Binding
当使用基于套接字的机制时,指定事务管理者进行恢复和生成事务标识符时使用的套接字绑定的名称。关于生成唯一标识符的更多信息,请参考 process-id-socket-max-ports。您可以在管理控制台的 Server 标签页上为每个服务器组指定套接字绑定。
/profile=default/subsystem=transactions/:write-attribute(name=socket-binding,value=txn-recovery-environment)
Recovery Listener
事务恢复进程是否应该侦听网络接口。默认值为 false
/profile=default/subsystem=transactions/:write-attribute(name=recovery-listener,value=false)
下面是高级选项,只能用管理 CLI 进行修改。根据默认配置进行修改时请小心行事。更多信息请联系红帽全球支持服务。
Expand
表 18.2. 高级 TM 配置选项
选项 描述 CLI 命令
jts
是否使用 Java Transaction Service (JTS) 事务。默认值为 false,表示只使用 JTA 事务。
/profile=default/subsystem=transactions/:write-attribute(name=jts,value=false)
node-identifier
JTS 服务的节点标识符。对于 JTS 服务它应该是唯一的,因为事务管理者会将它用于恢复过程。
/profile=default/subsystem=transactions/:write-attribute(name=node-identifier,value=1)
process-id-socket-max-ports
事务管理者为每个事务日志创建唯一的标识符。为生成唯一标识符提供两个不同的机制:基于套接字和基于进程标识符。
对于基于套接字的标识符,套接字被打开,其端口号用过标识符。如果端口已在使用,将探测下一个端口,直到找到空闲的端口。process-id-socket-max-ports 代表 TM 在失败前将尝试的最多套接字数量。默认值是 10
/profile=default/subsystem=transactions/:write-attribute(name=process-id-socket-max-ports,value=10)
process-id-uuid
true 表示使用进程标识符来为每个事务创建唯一的标识符。否则将使用基于套接字的机制。默认值为 true。更多信息请参考 process-id-socket-max-ports
/profile=default/subsystem=transactions/:write-attribute(name=process-id-uuid,value=true)
use-hornetq-store
对于事务日志,使用 HornetQ 的日志存储机制而不是基于文件的存储。这默认是禁用的,但可能会提高 I/O 性能。我们不推荐对 JTS 事务使用独立的事务管理者。
/profile=default/subsystem=transactions/:write-attribute(name=use-hornetq-store,value=false)

18.1.3. 用 JTA 事务配置您的数据源

总结

本节展示了如何启用数据源上的 JTA。

前提条件

在开始安装前,你必须满足下列条件:

过程 18.1. 配置数据源以使用 JTA 事务

  1. 在文本编辑器里打开配置文件。

    根据您是否以受管域还是独立服务器运行 JBoss EAP 6,您的配置文件所处的位置不同。
    • 受管域

      受管域的默认配置文件对于 Red Hat 企业版来说,位于 EAP_HOME/domain/configuration/domain.xml,对于 Microsoft Windows 则位于 EAP_HOME\domain\configuration\domain.xml
    • 独立服务器

      独立服务器的默认配置文件对于 Red Hat 企业版 Linux 来说,位于 EAP_HOME/standalone/configuration/standalone.xml,对于 Microsoft Windows,位于 EAP_HOME\standalone\configuration\standalone.xml
  2. 定位对应数据源的 <datasource> 标签。

    数据源将 jndi-name 属性设置为您创建时指定的值。例如,ExampleDS 数据源应类似于:
    <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="H2DS" enabled="true" jta="true" use-java-context="true" use-ccm="true">
  3. 设置 jta 属性为 true

    和之前的步骤一样,添加下列内容到 <datasource> 标记里:jta="true"
  4. 保存配置文件。

    保存配置文件并退出文本编辑器。
  5. 启动 JBoss EAP 6。

    重新启动 JBoss EAP 6 服务器。
结果:

JBoss EAP 6 已启动且配置您的数据源使用 JTA 事务。

18.1.4. 配置 XA 数据源

前提条件

为了添加 XA 数据源,你需要登录至管理控制台。详情请参考 第 3.4.2 节 “登录到管理控制台”

  1. 添加新的数据源。

    添加新的数据源到 JBoss EAP 6。请按照 第 6.3.1 节 “用管理界面创建一个 Non-XA 数据源” 里的步骤,但要点击顶部的 XA Datasource 标签。
  2. 配置其他属性。

    第 6.6.1 节 “数据源参数” 列出了所有的数据源参数。
结果

配置好的 XA 数据源可以使用了。

18.1.5. 关于事务日志消息

要跟踪事务状态同时也使日志文件可读,对事务 logger 请使用 DEBUG 日志级别。详细地调试信息则使用 TRACE 日志级别。关于配置事务 logger 的信息,请参考 第 18.1.6 节 “为事务子系统配置日志”
当配置为 TRACE 日志级别时,事务管理者可以生成大量的日志信息。下面是一些最常见的信息。这个列表并不完整,所以实际环境里您可能会看到其他信息。
Expand
表 18.3. 事务状态变化
Transaction Begin
当事务开始时,下列代码将被执行:
com.arjuna.ats.arjuna.coordinator.BasicAction::Begin:1342
tsLogger.logger.trace("BasicAction::Begin() for action-id "+ get_uid());
Transaction Commit
当事务提交时,下列代码将被执行:
com.arjuna.ats.arjuna.coordinator.BasicAction::End:1342
tsLogger.logger.trace("BasicAction::End() for action-id "+ get_uid());
事务回滚
当事务回滚时,下列代码将被执行:
com.arjuna.ats.arjuna.coordinator.BasicAction::Abort:1575
tsLogger.logger.trace("BasicAction::Abort() for action-id "+ get_uid());
事务超时
当事务超时时,下列代码将被执行:
com.arjuna.ats.arjuna.coordinator.TransactionReaper::doCancellations:349
tsLogger.logger.trace("Reaper Worker " + Thread.currentThread() + " attempting to cancel " + e._control.get_uid());
您将看到相同的线程回滚上面显示的事务。

18.1.6. 为事务子系统配置日志

概述

使用这个过程来控制事务日志信息的数量,它独立于 JBoss EAP 6 里的其他日志设置。主过程展示了如何在基于 Web 的管理控制台里实现这一点。随后给出了管理 CLI 命令。

过程 18.2. 用管理控制台配置事务 Logger

  1. 进入日志配置区域。

    在管理控制台里,点击屏幕左上角的 Profiles 标签页。如果您在使用受管域,请在右上角的 Profile 选择框里选择要配置的服务器配置集。
    展开 Core 菜单,点击 Logging 标签。
  2. 编辑 com.arjuna 属性。

    点击屏幕底部的 Details 部分的 Edit 按钮。在这里您可以添加类专有的日志信息。com.arjuna 类是现有的。您可以修改日志级别以及是否使用父处理程序。
    日志级别
    默认的日志级别是 WARN。因为事务可以产生大量的日志输出,标准日志级别对于事务 logger 来说有稍许不同。通常比所选日志级别严重性较低的消息会被舍弃。

    事务日志级别,从最精简到最冗余。

    • TRACE
    • DEBUG
    • INFO
    • WARN
    • ERROR
    • FAILURE
    使用父处理程序
    Logger 是否应该将输出发送到父 Logger。默认行为是 true
  3. 修改会立即生效。

18.2. 事务管理

18.2.1. 浏览并管理事务

基于命令行的管理 CLI 有浏览和操纵事务记录的功能。这个功能是通过事务管理者和 JBoss EAP 6 的管理 API 交互作用来提供的。
事务管理者将每个待定事务和涉及的参与者的信息存储在一个名为对象库(object store)的持久性存储里。管理 API 将对象库作为名为 log-store 的资源开放。名为 probe 的 API 操作读取事务日志并为每个日志创建一个节点。每当您需要刷新 log-store 时,您都可以手动调用 probe 命令。事务日志快速出现和消失都是正常的。

例 18.1. 刷新日志库

这个命令刷新了在受管域里使用配置集 default 的服务器组的日志库。对于独立服务器,请从命令里删除 profile=default
/profile=default/subsystem=transactions/log-store=log-store/:probe

例 18.2. 查看所有 Prepared 事务

要查看所有 Prepared 事务,首先请刷新日志库(请参考 例 18.1 “刷新日志库”),然后运行下列命令(功能类似于文件系统的 ls 命令)。
ls /profile=default/subsystem=transactions/log-store=log-store/transactions
这会展示每个事务及其唯一的标识符。可对单独的事务执行单独的操作(请参考 管理事务)。

管理事务

查看事务的属性。
要查看事务的信息,如 JNDI 名称、EIS 产品名和版本或状态,请使用 :read-resource CLI 命令。
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:read-resource
查看事务的参与者。
每个事务日志都包含一个名为 participants 的子元素。对这个元素使用 read-resource CLI 命令来查看事务的参与者。参与者是通过它们的 JNDI 名称来标识的。
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9/participants=java\:\/JmsXA:read-resource
结果可能类似于:
{
   "outcome" => "success",
   "result" => {
       "eis-product-name" => "HornetQ",
       "eis-product-version" => "2.0",
       "jndi-name" => "java:/JmsXA",
       "status" => "HEURISTIC",
       "type" => "/StateManager/AbstractRecord/XAResourceRecord"
   }
}
这里显示的结果状态是 HEURISTIC 且符合恢复的条件。详情请参考 恢复事务。
删除事务。
每个事务日志都支持 :delete 操作来删除代表事务的事务日志。
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:delete
恢复事务。
每个事务都支持通过 :recover CLI 命令进行恢复。

恢复启发式事务和参与者

  • 如果事务的状态是 HEURISTIC,恢复操作会修改其状态为 PREPARE 并触发恢复。
  • 如果事务的其中一个参与者是启发式的,恢复操作会试图重新执行 commit 操作。如果成功,参与者将从事务日志里删除。您可以通过在 log-store 上重新运行 :probe 并检查参与者是否不再列出来验证这一点。如果这是最后一个参与者,事务也会被删除。
刷新需要恢复的事务的状态。
如果事务需要恢复,在进行恢复之前,您可以使用 :refresh CLI 命令确定它仍要求恢复。
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:refresh
查看事务统计信息

如果启用了事务管理者(Transaction Manager,TM)统计,您可以查看事务管理者和事务子系统的统计信息。关于如何启用 TM 统计的信息,请参考 第 18.1.2 节 “配置事务管理者”

您可以通过基于 Web 的管理控制台或命令行管理 CLI 来查看统计信息。在基于 Web 的管理控制台里,事务统计信息可以通过 RuntimeSubsystem MetricsTransactions 访问。事务统计信息对于受管域里的每台服务器都是可用的。您可以在左上角的 Server 选择框里指定服务器。
下表展示了每个可用的统计信息、描述和查看统计信息的 CLI 命令。
Expand
表 18.4. 事务子系统统计
统计 描述 CLI 命令
Total
服务器上事务管理者处理的事务总数。
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-transactions,include-defaults=true)
Committed
服务器上事务管理者提交的事务总数。
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-committed-transactions,include-defaults=true)
Aborted
服务器上事务管理者中止的事务总数。
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-aborted-transactions,include-defaults=true)
Timed Out
服务器上事务管理者处理的超时事务总数。
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-timed-out-transactions,include-defaults=true)
Heuristics
在管理控制台里不可用。处于 heuristic 状态的事务的数量。
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-heuristics,include-defaults=true)
In-Flight Transactions
在管理控制台里不可用。已经开始但还未终止的事务的数量。
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-inflight-transactions,include-defaults=true)
Failure Origin - Applications
故障来源是应用程序的失败事务的数量。
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-application-rollbacks,include-defaults=true)
Failure Origin - Resources
故障来源是资源的失败事务的数量。
/host=master/server=server-one/subsystem=transactions/:read-attribute(name=number-of-resource-rollbacks,include-defaults=true)

18.3. 事务引用

18.3.1. JBoss 事务的错误和异常

关于 UserTransaction 类的方法抛出的异常,请参考 http://download.oracle.com/javaee/1.3/api/javax/transaction/UserTransaction.html 上的 UserTransaction API 规格。

18.3.2. JTA 群集限制

JTA 事务不能在多个 EAP 实例间进行群集。你可以使用 JTS 事务来实现这一点。
要使用 JTS 事务,您需要配置 ORB,它包括在 JacORB 子系统里建立事务,然后配置 JTS 子系统。

18.4. ORB 配置

Common Object Request Broker Architecture (CORBA) 是一个启用应用程序和服务使其一起运行的标准,即使这些程序或服务是用多种不兼容的语言编写或运行在独立的平台上的。CORBA 请求由一个名为 Object Request Broker (ORB) 的服务器端的组件进行代理。JBoss EAP 6 提供一个 ORB 实例来作为 JacORB 组件。
这个 ORB 用于 Java Transaction Service (JTS) 事务内部,也可以供您自己的应用程序使用。

18.4.2. 为 JTS 事务配置 ORB

在默认的 JBoss EAP 6 的安装里,ORB 是禁用的。你可以用命令行管理 CLI 启用 ORB。

注意

在受管域里,JacORB 子系统只能用于 fullfull-ha 配置集。在独立服务器里,你可以使用 standalone-full.xmlstandalone-full-ha.xml 配置。

过程 18.3. 使用管理控制台配置 ORB

  1. 查看配置集设置。

    从管理控制台的右上角选择 Profiles (受管域) 或 Profile(独立服务器)。如果你使用了受管域,请在左上角选择 fullfull-ha 配置集。
  2. 修改 Initializers 设置

    展开左侧的 Subsystems 菜单,展开 Container 子菜单并点击 JacORB
    在主屏幕上出现的表单里,选择 Initializers 标签页并点击 Edit 按钮。
    通过设置 Securityon 来启用安全拦截器。
    要启用 JTS 里的 ORB,请设置 Transaction Interceptors 值为 on,而不是默认的 spec
    关于这些值的详细解释,请点击表单里的 Need Help? 链接。在完成编辑后请点击 Save
  3. 高级的 ORB 配置

    关于高级的配置选项,请参考表单的其他部分。每个部分都包含一个关于参数详细解释的 Need Help? 链接。
使用管理 CLI 配置 ORB

你可以使用管理 CLI 配置 ORB 的每个方面。下面的命令配置初始器为与上面过程里使用管理控制台相同的值。这是 JTS 里 ORB 的最小配置。

这些命令是为使用 full 配置集的受管域配置的。如果有必要,请根据需要修改这个配置集。如果你使用了独立服务器,请忽略命令行的 /profile=full 部分。

例 18.3. 启用安全拦截器

/profile=full/subsystem=jacorb/:write-attribute(name=security,value=on)

例 18.4. 启用 JTS 里的 ORB

/profile=full/subsystem=jacorb/:write-attribute(name=transactions,value=on)

例 18.5. 在 JacORB 子系统里启用事务

/profile=full/subsystem=jacorb/:write-attribute(name=transactions,value=on)

例 18.6. 在事务子系统里启用 JTS

/subsystem=transactions:write-attribute(name=jts,value=true)

18.5. JDBC 对象库的支持

18.5.1. 事务的 JDBC 库

您可以配置 JBoss Transactions 将 JDBC 数据库用作自己的存储。这消除了对应用程序服务器上昂贵的复制存储方案的需要,因为基于文件的 ObjectStore 对于失效切换和恢复都要求复制存储空间。
在事务子系统里用 CLI 工具设置下面两个属性可以启用它。
  1. use-jdbc-store 设置为 true
    /subsystem=transactions:write-attribute(name=use-jdbc-store, value=true)
  2. 设置 jdbc-store-datasource 为数据源要使用的 JNDI 名称。
    /subsystem=transactions:write-attribute(name=jdbc-store-datasource, value=java:jboss/datasources/TransDS)
下面是完整的属性列表。
Expand
表 18.5. 事务 JDBC 库属性
属性 描述

use-jdbc-store

设置为 "true" 为事务启用 JDBC 库。

jdbc-store-datasource

用于存储的 JDBC 数据源的 JNDI 名称。

jdbc-action-store-drop-table

在启动时丢弃并重新创建 Action Store 表。可选项,默认值为 "False"。

jdbc-action-store-table-prefix

Action Store 表名的前缀。可选项。

jdbc-communication-store-drop-table

在启动时丢弃并重新创建 Communication Store 表。可选项,默认值为 "False"。

jdbc-communication-store-table-prefix

Communication Store 表名的前缀。可选项。

jdbc-state-store-drop-table

在启动时丢弃并重新创建 State Store 表。可选项,默认值为 "False"。

jdbc-state-store-table-prefix

State Store 表名的前缀。可选项。

第 19 章 邮件子系统

19.1. 在邮件子系统里使用自定义传输

当使用标准的邮件服务器(POP3、IMAP)时,服务器可以定义一系列属性,其中一些是必需的。
最重要的属性是 outbound-socket-binding-ref,它是对转出邮件套接字绑定的引用,且是用主机地址和端口号码来定义的。
对于某些用户来说,这并非最有效的解决方案,因为他们的主机配置将多个主机用于负载平衡。然而,要求用户实现自定义邮件传输的标准的 JavaMail 不支持这个配置。
这些自定义的传输不要求 outbound-socket-binding-ref 且允许自定义的主机属性格式。
自定义传输可以通过下列 CLI 命令来进行配置:

过程 19.1. 

  1. 添加新的邮件会话。下面的命令创建名为 mySession 的新会话并设置 JNDI 为 java:jboss/mail/MySession
    /subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
  2. 添加转出套接字绑定。下面的命令添加了名为 my-smtp-binding 的套接字绑定,它指向 localhost:25
    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp-binding:add(host=localhost, port=25)
  3. outbind-socket-binding-ref 添加 STMP 服务器。下面的命令添加一个名为 my-smtp-binding 的 SMTP,并定义一个用户名、密码和 TLS 配置。
    /subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref= my-smtp-binding, username=user, password=pass, tls=true)
    
  4. 对 POP3 和 IMAP 重复这个过程:
    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-pop3-binding:add(host=localhost, port=110)
    
    /subsystem=mail/mail-session=mySession/server=pop3:add(outbound-socket-binding-ref=my-pop3-binding, username=user, password=pass)
    
    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-imap-binding:add(host=localhost, port=143)
    
    /subsystem=mail/mail-session=mySession/server=imap:add(outbound-socket-binding-ref=my-imap-binding, username=user, password=pass)
    
  5. 要使用自定义服务器,创建一个新的不带有转出套接字绑定(因为是可选项)的自定义邮件服务器,并将主机信息作为属性的一部分来提供。
    /subsystem=mail/mail-session=mySession/custom=myCustomServer:add(username=user,password=pass, properties={"host" => "myhost", "my-property" =>"value"})
    
    在定义自定义协议时,任何包含句点(.)的属性名都被当作全限定名且直接传入。任何其他格式(如 my-property)将转换程下列格式:mail.server-name.my-property
下面是一个完整的 XML 配置示例,它在 custom-server 属性里强调了自定义格式:
<subsystem xmlns="urn:jboss:domain:mail:1.1">
    <mail-session jndi-name="java:/Mail" from="user.name@domain.org">
        <smtp-server outbound-socket-binding-ref="mail-smtp" tls="true">
            <login name="user" password="password"/>
        </smtp-server>
        <pop3-server outbound-socket-binding-ref="mail-pop3"/>
        <imap-server outbound-socket-binding-ref="mail-imap">
            <login name="nobody" password="password"/>
        </imap-server>
    </mail-session>
    <mail-session debug="true" jndi-name="java:jboss/mail/Default">
        <smtp-server outbound-socket-binding-ref="mail-smtp"/>
    </mail-session>
    <mail-session debug="true" jndi-name="java:jboss/mail/Custom">
        <custom-server name="smtp">
            <login name="username" password="password"/>
            <property name="host" value="mail.example.com"/>
        </custom-server>
        <custom-server name="pop3" outbound-socket-binding-ref="mail-pop3">
            <property name="custom_prop" value="some-custom-prop-value"/>
            <property name="some.fully.qualified.property" value="fully-qualified-prop-name"/>
        </custom-server>
    </mail-session>
    <mail-session debug="true" jndi-name="java:jboss/mail/Custom2">
        <custom-server name="pop3" outbound-socket-binding-ref="mail-pop3">
            <property name="custom_prop" value="some-custom-prop-value"/>
        </custom-server>
    </mail-session>
</subsystem>

第 20 章 Enterprise JavaBean

20.1. 简介

20.1.1. Enterprise JavaBean 概述

EJB 3.1 是开发分布式、事务性、安全和可移植 Java EE 应用程序的 API,它使用了名为 Enterprise Bean 的服务器端组件。EJB 以鼓励代码重用的松耦合方式实现了应用程序的商业逻辑。EJB 3.1 是作为 Java EE 规格 JSR-318 编写文档的。
JBoss EAP 6 对使用 EJB 3.1 规格构建的应用程序提供了完整的支持。EJB 容器是用 JBoss EJB3 社区项目实现的:http://www.jboss.org/ejb3

20.1.2. 用于管理员的 EJB 概述

JBoss 管理员可以通过许多配置选项来控制 JBoss EAP 6 里的 EJB 的性能。这些选项可以通过管理控制台或命令行配置工具来访问。编辑 XML 服务器配置文件来应用修改也是可能的,但我们不推荐这么做。
根据服务器运行的方式,EJB 配置选项在管理控制台里所处的位置会有轻微的不同。
如果服务器作为独立服务器来运行:
  1. 点击右上角的 Profile 链接来切换到 Profile 视图。
  2. 点击标签右边的箭头,展开左侧的 Profile 菜单。
  3. 点击 Container 展开它,然后点击 EJB 3
如果服务器是作为受管域的一部分运行:
  1. 点击顶部的 Profile 链接切换至『Profile』视图。
  2. 点击标签后面的箭头来展开 Subsystems 菜单。
  3. Profile 菜单里选择您在修改的配置集。
  4. 点击 Container 展开它,然后点击 EJB 3

20.1.3. Enterprise Bean

如 EJB 3.1 规格 JSR-318 里所定义的,Enterprise bean 是服务器端的组件。Enterprise bean 的目的是以分离的方式实现应用程序商业逻辑,从而鼓励重用。
EJB 以 Java 类编写且用合适的 EJB 注解进行注解。它们可以部署到自己归档(JAR 文件)里的应用服务器,也可以作为 Java EE 应用程序的一部分进行部署。应用服务器管理每个 EJB 的生命周期并提供服务,如安全性、事务和并行管理。
EJB 也可以定义任意数量的商业接口。商业接口提供对 bean 的哪些方法可被客户使用的更多控制,且允许访问运行在远程 JVM 里的客户。
有三种类型的 EJB:Session beans、Message-driven beans 和 Entity beans。

重要

EJB 3.1 里现在已废弃了 Entity Bean,Red Hat 推荐使用 JPA 实体来替代。Red Hat 只推荐出于对以前的系统的向后兼容性才使用 Entity Bean。

20.1.4. Session Beans

Session Bean 是封装了相关商业过程或任务的 EJB,它被注入到请求它们的类里。有三种 Session Bean:stateless、stateful 和 singleton。

20.1.5. Message-Driven Bean

Message-driven Bean(MDB) 为应用程序的开发提供了一个事件驱动的模型。MDB 的方法不会注入或从客户代码里调用,但会被消息服务(如 JMS 服务器)里的消息触发。Java EE 6 规格要求只支持 JMS,但也可以支持其他的消息系统。

20.2. 配置 Bean 池

20.2.1. Bean 池

JBoss EAP 6 在内存里维护着大量的已部署的 stateless EJB 以提供更好的性能。这个技术被称为 Bean Pooling。当 Bean 被请求时,应用服务器可以从池里取出已可用的合适的 bean 而不是创建一个新的。当 bean 不再被需要时,它将被返回到池里以供重用。
对于 stateless session bean 和 message-driven bean,Bean 池是单独配置和维护的。

20.2.2. 创建 Bean 池

Bean 池可以用管理控制台和 CLI 工具来创建。
您可以通过添加所需的 Bean 池配置到服务器配置文件来创建 Bean 池。例 20.2 “XML 配置示例” 是一个配置文件的例子。

过程 20.1. 用管理控制台来创建 Bean 池

  1. 登录到管理控制台。请参考 第 3.4.2 节 “登录到管理控制台”
  2. 点击右上角的 Profile,展开左边『Profile』面板里的 Container 并 选择 EJB 3。然后从主面板里选择 Bean Pools 标签页。
  3. 点击 Add 按钮。Add EJB3 Bean Pools 对话框将会出现。
  4. 指定所需的细节,包括:NameMax Pool SizeTimeoutTimeout
  5. 点击 Save 按钮来保存新的 bean 池或点击 Cancel 链接来中止这个过程。
    • 如果您点击 Save 按钮,对话框将关闭而新的 Bean 池将出现在列表里。
    • 如果您点击 Cancel,对话框将被关闭且不会有新的 Bean 池被创建。

过程 20.2. 用 CLI 创建 Bean 池

  1. 登录 CLI 工具并连接到您的服务器。请参考 第 3.5.4 节 “用管理 CLI 连接受管服务器实例”
  2. 使用 add 操作及下列语法。
    /subsystem=ejb3/strict-max-bean-instance-pool=BEANPOOLNAME:add(max-pool-size=MAXSIZE, timeout=TIMEOUT, timeout-unit="UNIT")
    • 用 Bean 池的名称替换 BEANPOOLNAME
    • 用 Bean 池的最大大小替换 MAXSIZE
    • 替代 TIMEOUT
    • 用所需的时间单元替代 UNIT。所允许的值有:NANOSECONDSMICROSECONDSMILLISECONDSSECONDSMINUTESHOURSDAYS
  3. 请用 read-resource 操作来确认 Bean 池的创建。
    /subsystem=ejb3/strict-max-bean-instance-pool=BEANPOOLNAME:read-resource

例 20.1. 用 CLI 创建 Bean 池

[standalone@localhost:9999 /] /subsystem=ejb3/strict-max-bean-instance-pool=ACCTS_BEAN_POOL:add(max-pool-size=500, timeout=5000, timeout-unit="SECONDS")  
{"outcome" => "success"}
[standalone@localhost:9999 /]

例 20.2. XML 配置示例

<subsystem xmlns="urn:jboss:domain:ejb3:1.2">

   <pools>

      <bean-instance-pools>

         <strict-max-pool  name="slsb-strict-max-pool" max-pool-size="20" 
            instance-acquisition-timeout="5" 
            instance-acquisition-timeout-unit="MINUTES" />

         <strict-max-pool name="mdb-strict-max-pool" max-pool-size="20" 
            instance-acquisition-timeout="5" 
            instance-acquisition-timeout-unit="MINUTES" />

      </bean-instance-pools>

   </pools>

</subsystem>

20.2.3. 删除 Bean 池

未使用的 Bean 池可以用管理控制台进行删除。

预备条件:

过程 20.3. 用管理控制台来删除 Bean 池

  1. 登录到管理控制台。请参考 第 3.4.2 节 “登录到管理控制台”
  2. 点击右上角的 Profile,展开左边『Profile』面板里的 Container 并 选择 EJB 3。然后从主面板里选择 Bean Pools 标签页。
  3. 从列表里选择要删除的 Bean 池。
  4. 点击 Remove 按钮。Remove Item 对话框将会出现。
  5. 点击 OK 按钮确认删除或点击 Cancel 链接来中止操作。
    如果您点击 Ok 按钮,对话框将关闭而 Bean 池将从列表里删除。
    如果您点击了 Cancel,对话框将关闭且不会保存任何修改。

过程 20.4. 用 CLI 删除 Bean 池

  1. 登录 CLI 工具并连接到您的服务器。请参考 第 3.5.4 节 “用管理 CLI 连接受管服务器实例”
  2. 使用 remove 操作和下列语法。
    /subsystem=ejb3/strict-max-bean-instance-pool=BEANPOOLNAME:remove
    • 用 Bean 池的名称替换 BEANPOOLNAME

例 20.3. 用 CLI 删除 Bean 池

[standalone@localhost:9999 /] /subsystem=ejb3/strict-max-bean-instance-pool=ACCTS_BEAN_POOL:remove  
{"outcome" => "success"}
[standalone@localhost:9999 /]

20.2.4. 编辑 Bean 池

Bean 池可以用管理控制台进行编辑。

过程 20.5. 用管理控制台编辑 Bean 池

  1. 点击右上角的 Profile,展开左边『Profile』面板里的 Container 并 选择 EJB 3。然后从主面板里选择 Bean Pools 标签页。
  2. 从列表里选择要编辑的 Bean 池。
  3. 点击 编辑 按钮。Details 区域里的字段现在可以进行编辑了。
  4. 编辑要修改的内容,您只可以修改 Max Pool SizeTimeoutTimeout
  5. 修改完成后点击 Save 按钮,如果想取消修改则点击 Cancel
    如果您点击 Ok 按钮,Details 区域将变成不可编辑的表单,且 Bean 池将用新的内容更新。
    如果您点击 Cancel 链接,Details 区域将变成不可编辑的表单,内容也没有变化。

过程 20.6. 用 CLI 编辑 Bean 池

  1. 登录 CLI 工具并连接到您的服务器。请参考 第 3.5.4 节 “用管理 CLI 连接受管服务器实例”
  2. 对需要修改的每个属性使用 write-attribute 操作和下列语法。
    /subsystem=ejb3/strict-max-bean-instance-pool=BEANPOOLNAME:write-attribute(name="ATTRIBUTE", value="VALUE")
    • 用 Bean 池的名称替换 BEANPOOLNAME
    • 用要编辑的属性的名称替换 ATTRIBUTE。可以编辑的这些属性是 max-pool-size, timeouttimeout-unit.
    • 用所需的属性值替换 VALUE
  3. 请用 read-resource 操作来确认对 Bean 池的修改。
    /subsystem=ejb3/strict-max-bean-instance-pool=BEANPOOLNAME:read-resource

例 20.4. 用 CLI 设置 Bean 池的 Timeout 值

[standalone@localhost:9999 /] /subsystem=ejb3/strict-max-bean-instance-pool=HSBeanPool:write-attribute(name="timeout", value="1500")
{"outcome" => "success"}
[standalone@localhost:9999 /]

20.2.5. 为 Session 和 Message-Driven Bean 分配 Bean 池

JBoss 管理员可以通过管理控制台或 CLI 分别为 Session Bean 或 Message-driven Bean 分配独立的 Bean 池。
默认情况下有两种 Bean 池,分别用于 stateless session bean 的 slsb-strict-max-pool 和用于 message-driven bean 的 mdb-strict-max-pool

过程 20.7. 用管理控制台为 Message-Driven Bean 分配 Bean 池

  1. 进入 EJB3 容器配置面板。
  2. 点击 编辑 按钮。Details 区域里的字段现在可以进行编辑了。
  3. 从合适的组合框里为每种 Bean 选择 Bean 池。
  4. 点击 Save 按钮保存修改,如果想取消修改则点击 Cancel
  5. Details 区域变成不可编辑的并显示正确的 Bean 池选择。

过程 20.8. 用 CLI 为 Message-Driven Bean 分配 Bean 池

  1. 登录 CLI 工具并连接到您的服务器。请参考 第 3.5.4 节 “用管理 CLI 连接受管服务器实例”
  2. 请使用 write-attribute 命令和下列语法。
    /subsystem=ejb3:write-attribute(name="BEANTYPE", value="BEANPOOL")
    • 对于 Message-Driven Bean,用 default-mdb-instance-pool 替换 BEANTYPE,而对于 stateless session bean 则使用 default-slsb-instance-pool
    • 用分配的 Bean 池的名称替换 BEANPOOL
  3. 使用 read-resource 操作来确认修改。
    /subsystem=ejb3:read-resource

例 20.5. 用 CLI 为 Session Bean 分配 Bean 池

[standalone@localhost:9999 /] /subsystem=ejb3:write-attribute(name="default-slsb-instance-pool", value="LV_SLSB_POOL")  
{"outcome" => "success"}
[standalone@localhost:9999 /]

例 20.6. XML 配置示例

<subsystem xmlns="urn:jboss:domain:ejb3:1.2">
   <session-bean>
      <stateless>
         <bean-instance-pool-ref pool-name="slsb-strict-max-pool"/>
      </stateless>
      <stateful default-access-timeout="5000" cache-ref="simple"/>
      <singleton default-access-timeout="5000"/>
   </session-bean>
   <mdb>
      <resource-adapter-ref resource-adapter-name="hornetq-ra"/>
      <bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>
   </mdb>


</subsystem>

20.3. 配置 EJB 线程池

20.3.1. EJB 线程池

JBoss EAP 6 在内存里维护着大量的 EJB 服务使用的 Java 线程对象实例,包括远程调用、定时器服务和异步调用。
这个技术被称为线程池。它通过消除创建线程的负荷来提高性能,而且让系统管理员有了控制资源使用的机制。
用不同的参数可以创建多个线程池,且每个服务都可以分配不同的线程池。

20.3.2. 创建线程池

EJB 线程池可以用管理控制台或 CLI 来创建。

过程 20.9. 用管理控制台来创建 EJB 线程池

  1. 点击右上角的 Profile,展开左边『Profile』面板里的 Container 并 选择 EJB 3。然后从主面板里选择 Thread Pools 标签页。
  2. 点击 Add 按钮。Add EJB3 Thread Pools 对话框将会出现。
  3. 指定所需的细节,如 NameMax. ThreadsKeep-Alive Timeout 等。
  4. 点击 Save 按钮来保存新的线程池或点击 Cancel 链接来中止这个过程。
    • 如果您点击 Save 按钮,对话框将关闭而新的线程池将出现在列表里。
    • 如果您点击 Cancel,对话框将被关闭且不会有新的线程池被创建。

过程 20.10. 用 CLI 创建线程池

  1. 登录 CLI 工具并连接到您的服务器。请参考 第 3.5.4 节 “用管理 CLI 连接受管服务器实例”
  2. 使用 add 操作和下列语法。
    /subsystem=ejb3/thread-pool=THREADPOOLNAME:add(max-threads=MAXSIZE, keepalive-time={"time"=>"TIME", "unit"=>UNIT"})
    • 用线程池的名称替换 THREADPOOLNAME
    • 用线程池的最大大小替换 MAXSIZE
    • 用保持在线所需的时间单元替代 UNIT。所允许的值有:NANOSECONDSMICROSECONDSMILLISECONDSSECONDSMINUTESHOURSDAYS
    • 用保持在线所需的时间替换 TIME。这个值是一个 UNIT 数字。
  3. 请用 read-resource 操作来确认 Bean 池的创建。
    /subsystem=ejb3/strict-max-bean-instance-pool=THREADPOOLNAME:read-resource

例 20.7. 用 CLI 创建线程池

[standalone@localhost:9999 /] /subsystem=ejb3/thread-pool=testmepool:add(max-threads=50, keepalive-time={"time"=>"150", "unit"=>"SECONDS"})
{"outcome" => "success"}
[standalone@localhost:9999 /]

例 20.8. XML 配置示例

<subsystem xmlns="urn:jboss:domain:ejb3:1.2">

   <thread-pools>
      <thread-pool name="default" max-threads="20" keepalive-time="150"/>
   </thread-pools>

</subsystem>

20.3.3. 删除线程池

未使用的线程池可以用管理控制台进行删除。

前提条件

过程 20.11. 用管理控制台来删除 EJB 线程池

  1. 登录到管理控制台。第 3.4.2 节 “登录到管理控制台”
  2. 点击右上角的 Profile,展开左边『Profile』面板里的 Container 并 选择 EJB 3。然后从主面板里选择 Thread Pools 标签页。
  3. 从列表里选择要删除的线程池。
  4. 点击 Remove 按钮。Remove Item 对话框将会出现。
  5. 点击 OK 按钮确认删除或点击 Cancel 链接来中止操作。
    如果您点击 Ok 按钮,对话框将关闭而线程池将从列表里删除。
    如果您点击了 Cancel,对话框将关闭且不会保存任何修改。

过程 20.12. 用 CLI 删除线程池

  1. 登录 CLI 工具并连接到您的服务器。请参考 第 3.5.4 节 “用管理 CLI 连接受管服务器实例”
  2. 使用 remove 操作和下列语法。
    /subsystem=ejb3/thread-pool=THREADPOOLNAME:remove
    • 用线程池的名称替换 THREADPOOLNAME

例 20.9. 用 CLI 删除线程池

[standalone@localhost:9999 /] /subsystem=ejb3/thread-pool=ACCTS_THREADS:remove
{"outcome" => "success"}
[standalone@localhost:9999 /]

20.3.4. 编辑线程池

JBoss 管理员可以用管理控制台或 CLI 来编辑线程池。

过程 20.13. 用管理控制台编辑线程池

  1. 登录

    登陆到管理控制台。
  2. 导航至 EJB3 线程池标签页

    点击右上角的 Profile,展开左边『Profile』面板里的 Container 并 选择 EJB 3。然后从主面板里选择 Thread Pools 标签页。
  3. 选择要编辑的线程池

    从列表里选择要编辑的线程池。
  4. 点击 Edit 按钮

    Details 里的字段现在是可编辑的了。
  5. 编辑细节

    编辑要修改的内容,您只可以修改 Thread FactoryMax ThreadsKeepalive TimeoutKeepalive Timeout Unit
  6. 保存或取消

    修改完成后点击 Save 按钮,如果想取消修改则点击 Cancel

过程 20.14. 用 CLI 编辑线程池

  1. 登录 CLI 工具并连接到您的服务器。请参考 第 3.5.4 节 “用管理 CLI 连接受管服务器实例”
  2. 对需要修改的每个线程池属性使用 write_attribute 操作和下列语法。
    /subsystem=ejb3/thread-pool=THREADPOOLNAME:write-attribute(name="ATTRIBUTE", value="VALUE")
    • 用线程池的名称替换 THREADPOOLNAME
    • 用要编辑的属性的名称替换 ATTRIBUTE。可以编辑的这些属性是 keepalive-timemax-threadsthread-factory
    • 用所需的属性值替换 VALUE
  3. 请用 read-resource 操作来确认对线程池的修改。
    /subsystem=ejb3/thread-pool=THREADPOOLNAME:read-resource

重要

当用 CLI 修改 keepalive-time 属性的值时,所需的值是一个对象形式。它具有下列语法。
/subsystem=ejb3/thread-pool=THREADPOOLNAME:write-attribute(name="keepalive-time", value={"time" => "VALUE","unit" => "UNIT"}

例 20.10. 用 CLI 设置线程池的 Maxsize 值

[standalone@localhost:9999 /] /subsystem=ejb3/thread-pool=HSThreads:write-attribute(name="max-threads", value="50")
{"outcome" => "success"}
[standalone@localhost:9999 /]

例 20.11. 用 CLI 设置线程池的 keepalive-time

[standalone@localhost:9999 /] /subsystem=ejb3/thread-pool=HSThreads:write-attribute(name="keepalive-time", value={"time"=>"150"})
{"outcome" => "success"}
[standalone@localhost:9999 /]

20.4. 配置 Session Bean

20.4.1. Session Bean 访问超时

Stateful 和 Singleton Session Bean 有一个用于管理并行访问的访问超时值。这个值指定对 Session Bean 的方法的请求超时前阻塞的时间。
超时值和单位可以用 @javax.ejb.AccessTimeout 注解指定。它可以在 Session Bean(应用于所有的方法)或某个方法上指定来覆盖 Bean 的配置。
如果没有指定,JBoss EAP 6 将提供一个默认的超时值 5000 毫秒。

20.4.2. 设置默认的 Session Bean 访问超时时间

JBoss 管理员可以指定默认的 Singleton 和 Stateful Session Bean 的超时时间。默认值可以通过管理控制台或 CLI 设置。其默认值是 5000 毫秒。

过程 20.15. 用管理控制台设置默认的 Session Bean 访问超时时间

  1. 登录到管理控制台。请参考 第 3.4.2 节 “登录到管理控制台”
  2. 点击右上角的 Profile,展开左边『Profile』面板里的 Container 并 选择 EJB 3。然后从主面板里选择 Container 标签页。
  3. 点击 编辑 按钮。Details 区域里的字段现在可以进行编辑了。
  4. Stateful Access Timeout 和/或 Singleton Access Timeout 文本框里输入所需的值。
  5. 点击 Save 按钮保存修改,如果想取消修改则点击 Cancel
  6. Details 区域变成不可编辑的并显示正确的超时值。

过程 20.16. 用 CLI 设置 Session Bean 访问超时时间

  1. 登录 CLI 工具并连接到您的服务器。请参考 第 3.5.4 节 “用管理 CLI 连接受管服务器实例”
  2. 请使用 write-attribute 命令和下列语法。
    /subsystem=ejb3:write-attribute(name="BEANTYPE", value=TIME)
    • 对于 Stateful Session Bean,用 default-stateful-bean-access-timeout 替换 BEANTYPE,而对于 Singleton Session bean 则使用 default-singleton-bean-access-timeout
    • 用所需的超时值替换 TIME
  3. 使用 read-resource 操作来确认修改。
    /subsystem=ejb3:read-resource

例 20.12. 用 CLI 设置默认的 Session Bean 访问超时时间为 9000

[standalone@localhost:9999 /] /subsystem=ejb3:write-attribute(name="default-stateful-bean-access-timeout", value=9000)  
{"outcome" => "success"}
[standalone@localhost:9999 /]

例 20.13. XML 配置示例

<subsystem xmlns="urn:jboss:domain:ejb3:1.2">
   <session-bean>
      <stateless>
         <bean-instance-pool-ref pool-name="slsb-strict-max-pool"/>
      </stateless>
      <stateful default-access-timeout="5000" cache-ref="simple"/>
      <singleton default-access-timeout="5000"/>
   </session-bean>
   
</subsystem>

20.5. 配置 Message-Driven Bean

JBoss 管理员可以指定 Message-Driven Bean 使用的默认资源适配器。这个默认的资源适配器可以通过管理控制台或 CLI 设置。JBoss EAP 6 提供的默认值是 hornetq-ra

过程 20.17. 用管理控制台为 Message-Driven Bean 设置默认的资源适配器

  1. 点击右上角的 Profile,展开左边『Profile』面板里的 Container 并 选择 EJB 3。然后从主面板里选择 Container 标签页。
  2. 点击 编辑 按钮。Details 区域里的字段现在可以进行编辑了。
  3. Default Resource Adapter 文本框里输入要使用的资源适配器名称。
  4. 点击 Save 按钮保存修改,如果想取消修改则点击 Cancel
  5. Details 区域变成不可编辑的并显示正确的资源适配器名称。

过程 20.18. 用 CLI 为 Message-Driven Bean 设置默认的资源适配器

  1. 登录 CLI 工具并连接到您的服务器。请参考 第 3.5.4 节 “用管理 CLI 连接受管服务器实例”
  2. 请使用 write-attribute 命令和下列语法。
    /subsystem=ejb3:write-attribute(name="default-resource-adapter-name", value="RESOURCE-ADAPTER")
    用要使用的资源适配器名称替换 RESOURCE-ADAPTER
  3. 使用 read-resource 操作来确认修改。
    /subsystem=ejb3:read-resource

例 20.14. 用 CLI 为 Message-Driven Bean 设置默认的资源适配器

[standalone@localhost:9999 subsystem=ejb3] /subsystem=ejb3:write-attribute(name="default-resource-adapter-name", value="EDIS-RA")
{"outcome" => "success"}
[standalone@localhost:9999 subsystem=ejb3]

例 20.15. XML 配置示例

<subsystem xmlns="urn:jboss:domain:ejb3:1.2">

   <mdb>
      <resource-adapter-ref resource-adapter-name="hornetq-ra"/>
      <bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>
   </mdb>


</subsystem>

20.6. 配置 EJB3 定时器服务

20.6.1. EJB3 定时器服务

EJB3 定时器服务是一个标准的 Java EE 6 服务,用于调度 EJB 的方法调用。Stateless session beans、singleton session beans 和 message-driven bean 都可以在指定时间调度它们的回调方法。方法回调可以发生在指定的时间、以某个时间间隔循环发生或基于日历进行调度。

20.6.2. 配置 EJB3 定时器服务

JBoss 管理员可以在管理控制台里配置 EJB3 定时器服务。可以配置的功能是用于调度的线程池和定时器所数据保存的目录。

过程 20.19. 配置 EJB3 定时器服务

  1. 登录

    登陆到管理控制台。
  2. 打开定时器服务标签页

    点击右上角的 Profile,展开左边『Profile』面板里的 Container 并 选择 EJB 3。从主面板里选择 Services 标签页然后进入 Timer Service 标签页。
  3. 进入编辑模式

    点击 Edit 按钮,字段会变成可编辑的。
  4. 按需要进行修改。

    如果配置了其他线程池,您可以为定时器选择不同的 EJB3 线程池;您也可以修改保存定时器服务数据的目录。定时器服务数据目录的配置由两个值组成:Path,数据所保存的目录;Relative To,包含 Path 的目录。在默认情况下,Relative To 被设置为文件系统的 Path 变量。
  5. 保存或取消

    点击 Save 按钮保存修改,如果想取消修改则点击 Cancel

20.7. 配置 EJB 异步调用服务

20.7.1. EJB3 异步调用服务

异步调用服务(Asynchronous Invocation Service)是一个 EJB 容器服务,它管理 Session Bean 方法的异步调用。这个服务维护着可配置的数量的线程(线程池),分配给异步方法调用。
Enterprise JavaBeans 3.1 允许对 Session Bean(stateful、stateless 或 singleton)的任何方法进行注解以允许异步执行。

20.7.2. 配置 EJB3 异步调用服务线程池

JBoss 管理员可以在 JBoss EAP 6 管理控制台里配置 EJB3 异步调用服务来使用专有的线程池。

过程 20.20. 配置 EJB3 异步调用服务线程池

  1. 登录

    登陆到管理控制台。
  2. 打开『Async Service』标签页

    点击右上角的 Profile,展开左边『Profile』面板里的 Container 并 选择 EJB 3。从主面板里选择 Services 标签页然后进入 Async Service 标签页。
  3. 进入编辑模式

    点击 Edit 按钮,字段会变成可编辑的。
  4. 选择线程池

    从列表里选择要使用的 EJB3 线程池。这个线程池必须是已创建的线程池。
  5. 保存或取消

    点击 Save 按钮保存修改,如果想取消修改则点击 Cancel

20.8. 配置 EJB3 远程调用服务

20.8.1. EJB3 远程服务

EJB3 远程服务管理带有远程商业接口的 EJB 的远程执行。

20.8.2. 配置 EJB3 远程服务

JBoss 管理员可以在管理控制台里配置 EJB3 Remote 服务。可以配置的功能是用于远程调用的线程池和 EJB3 Remoting 频道所注册的连接器。

过程 20.21. 配置 EJB3 远程服务

  1. 登录

    登陆到管理控制台。
  2. 打开『Remote Service』标签页

    点击右上角的 Profile,展开左边『Profile』面板里的 Container 并 选择 EJB 3。从主面板里选择 Services 标签页然后进入 Remote Service 标签页。
  3. 进入编辑模式

    点击 Edit 按钮,字段会变成可编辑的。
  4. 按需要进行修改

    如果配置了其他线程池,您可以为远程服务选择不同的 EJB3 线程池;您也可以修改用来注册 EJB Remoting 频道的连接器。
  5. 保存或取消

    点击 Save 按钮保存修改,如果想取消修改则点击 Cancel

20.9. 配置 EJB 2.x Entity Bean

20.9.1. EJB Entity Bean

EJB Entity Bean 是 EJB 2.x 规格的类型,它表示保存在数据库里的持久性数据。Entity Bean 已被 JPA Entity 代替,且在 EJB 官方规格里已列为删除(削减)内容。Red Hat 不推荐使用 Entity Bean,除非是为了向后兼容。
在默认情况下,JBoss EAP 6 是禁用对 Entity Bean 的支持的。
容器管理的持久化(Container-Managed Persistence,CMP)是应用服务器提供的一个服务,它为 Entity Bean 提供数据持久化。

20.9.3. 启用 EJB 2.x 的容器管理持久化

容器管理持久化(Container-Managed Persistence,CMP)是由 org.jboss.as.cmp 扩展处理的。受管域和独立服务器的 full 配置(standalone-full.xml)里 CMP 默认是启用的。
要在不同的配置里启用 CMP,请在服务器配置文件的启用扩展列表里添加 org.jboss.as.cmp 模块。
<extensions>
        <extension module="org.jboss.as.cmp"/>
</extensions>
要在服务器配置里禁用 CMP,请从 org.jboss.as.cmp 模块里删除扩展条目。

20.9.4. 配置 EJB 2.x 的容器管理持久化

您可以配置 EJB 2.x 的容器管理持久化子系统以指定任何数量的密钥生成器。密钥生成器用于生成唯一的密钥以标识 CMP 服务持久化的每个实体。
您可以定义两种类型的密钥生成器:UUID 和 HiLo 密钥生成器。
基于 UUID 的生成器
基于 UUID 的生成器可用 UUID 创建密钥。基于 UUID 的生成器只需要具有唯一的名称,它不需要其他配置。
基于 UUID 的密钥生成器可以使用下列语法通过 CLI 添加:
 /subsystem=cmp/uuid-keygenerator=UNIQUE_NAME:add 

例 20.16. 添加 UUID 密钥生成器

要添加名为 uuid_identities 的基于 UUID 的密钥生成器,请使用这个 CLI 命令:
/subsystem=cmp/uuid-keygenerator=uuid_identities:add
这个命令创建的 XML 配置是:
<subsystem xmlns="urn:jboss:domain:cmp:1.0"> 
   <key-generators>
      <uuid name="uuid_identities" />
   </key-generators>
</subsystem>
HiLo 密钥生成器
HiLo 密钥生成器使用数据库来创建和存储标识密钥。HiLo 密钥生成器必须具有唯一的名称并配置指定用来存储数据、表名及存储密钥的字段的数据源的属性。
HiLo 密钥生成器可以使用下列语法通过 CLI 添加:
 /subsystem=cmp/hilo-keygenerator=UNIQUE_NAME/:add(property=value, property=value, ...) 

例 20.17. 添加 HiLo 密钥生成器

/subsystem=cmp/hilo-keygenerator=DB_KEYS/:add(create-table=false,data-source=java:jboss/datasources/ExampleDS,drop-table=false,id-column=cmp_key_ids,select-hi-ddl=select max(cmp_key_ids) from cmp_key_seq,sequence-column=cmp_key_seq,table-name=cmp-keys))
这个命令创建的 XML 配置是:
<subsystem xmlns="urn:jboss:domain:cmp:1.0"> 
   <key-generators>
      <hilo name="DB_KEYS">
         <create-table>false</create-table>
         <data-source>java:jboss/datasources/ExampleDS</data-source>
         <drop-table>false</drop-table>
         <id-column>cmp_key_ids</id-column>
         <select-hi-ddl>select max(cmp_key_ids) from cmp_key_seq</select-hi-ddl>
         <sequence-column>cmp_key_seq</sequence-column>
         <table-name>cmp-keys</table-name>
      </hilo>
   </key-generators>
</subsystem>

20.9.5. HiLo 密钥生成器使用的 CMP 子系统属性

Expand
表 20.1. HiLo 密钥生成器使用的 CMP 子系统属性
属性 数据类型 描述
block-size long
-
create-table boolean
如果为 TRUE 且名为 table-name 的表不存在,这个表将用 create-table-ddl 的内容创建。
create-table-ddl string
用来创建 table-name 里指定的表的 DDL 命令(如果这个表不存在且 create-tableTRUE)。
data-source token
用于连接数据库的数据源。
drop-table boolean
-
id-column token
-
select-hi-ddl string 将返回当前存储的最大密钥的 SQL 命令。
sequence-column token
-
sequence-name token
-
table-name token
用于存储密钥信息的表的名称。

21.1. 简介

21.1.1. 关于 Java EE Connector API (JCA)

JBoss EAP 6 提供了对 Java EE Connector API (JCA) 1.6 规格的完整支持。关于 JCA 规格的更多信息,请参考 JSR 322: Java EE Connector Architecture 1.6
资源适配器(Resource Adapter)是一个实现 Java EE Connector API (JCA) 架构的组件。它和数据源对象类似,但它提供了从企业新系统(EIS)和多种系统间的连接性,如数据库、消息系统、事务处理和企业资源计划系统(ERP)。
Java EE 连接器架构(JCA)定义了 Java EE 系统到外部各种企业信息系统(EIS)的标准架构。EIS 的例子包括 EARP 系统、大型机事务处理(TP)、数据库和消息系统。
JCA 1.6 提供了下列管理功能:
  • 连接
  • 事务
  • 安全性
  • 生命周期
  • 工作实例
  • 事务流入
  • 消息流入
JCA 1.6 是基于 JSR-322 http://jcp.org/en/jsr/detail?id=313 开发的。

21.1.3. 资源适配器

资源适配器是一个可部署的 Java EE 组件,它通过 Java 连接器架构(JCA)提供 Java EE 应用程序和企业信息系统(EIS)之间的通讯。 资源适配器通常由 EIS 供应商提供以便于它们的产品和 Java EE 应用程序的集成。
企业信息系统(EIS)可以是机构内部的任何软件系统。如 EAR、数据库系统、电子邮件服务器和私有消息系统。
资源适配器打包在可以部署到 JBoss EAP 6 的 RAR 文件里。RAR 文件也可以包含在 EAR 部署文件里。
JBoss EAP 6 配置文件里的 JCA 子系统控制 JCA 容器和资源适配器部署的普通设置。
JCA 子系统的关键元素

归档检验
  • 它设置了在部署单元上执行的归档检验。
  • 下表描述了您可以为归档检验设置的属性。
    Expand
    表 21.1. 归档检验属性
    属性 默认值 描述
    enabled true
    指定是否启用归档检验
    fail-on-error true
    指定部署失败时是否报告归档检验错误。
    fail-on-warn false
    指定部署失败时是否报告归档检验警告。
  • 如果归档没有正确实现 Java EE 连接器架构规格且启用了归档检验,在部署期间会出现描述这个问题的错误信息。例如:
    Severity: ERROR
    Section: 19.4.2 
    Description: A ResourceAdapter must implement a "public int hashCode()" method. 
    Code: com.mycompany.myproject.ResourceAdapterImpl
    
    Severity: ERROR
    Section: 19.4.2
    Description: A ResourceAdapter must implement a "public boolean equals(Object)" method.
    Code: com.mycompany.myproject.ResourceAdapterImpl
    
  • 如果没有指定归档检验,它会被认作已存在且 enabled 默认为 True。
Bean 检验
  • 这个设置确定 Bean 检验(JSR-303)是否在部署单元上执行。
  • 下表描述了您可以为 Bean 检验设置的属性。
    Expand
    表 21.2. Bean 检验属性
    属性 默认值 描述
    enabled true
    指定是否启用 Bean 检验。
  • 如果没有指定 Bean 检验,它会被认作已存在且 enabled 默认为 True。
Work Manager
  • 有两种 Work Manager:
    默认的 Work Manager
    默认的 Work Manager 及其线程池。
    自定义 Work Manager
    自定义 Work Manager 定义及其线程池。
  • 下表描述了您可以为 Work Manager 设置的属性。
    Expand
    表 21.3. Work Manager 的属性
    属性 描述
    name
    指定 Work Manager 的名称。对于自定义 Work Manager 这是必需的。
    short-running-threads
    标准 Work 实例的线程池。每个 Work Manager 都有一个短期运行的线程池。
    long-running-threads
    用于设置 LONG_RUNNING 的 JCA 1.6 Work 实例的线程池。每个 Work Manager 都有一个可选的长期期运行的线程池。
  • 下表描述了您可以为 Work Manager 线程池设置的属性。
    Expand
    表 21.4. 线程池的属性
    属性 描述
    allow-core-timeout
    Boolean 值,确定核心线程是否超时。默认为 False。
    core-threads
    核心线程池的大小。它必须比线程池的最大尺寸要小。
    queue-length
    队列的最大长度。
    max-thread
    线程池的最大尺寸。
    keepalive-time
    指定在开始工作后池线程应该保持的时间。
    thread-factory
    对线程工厂的引用。
Bootstrap contexts
  • 用来定义自定义引导上下文。
  • 下表描述了您可以为引导上下文设置的属性。
    Expand
    表 21.5. 引导上下文属性
    属性 描述
    name
    指定引导上下文的名称。
    workmanager
    指定用于这个上下文的 Work Manager 的名称。
缓存的连接管理者
  • 用于调试连接和支持事务里的 Lazy 连接建立,跟踪应用程序是否使用或正确释放它们。
  • 下表描述您可以为缓存连接管理者设置的属性。
    Expand
    表 21.6. 缓存连接管理者的属性
    属性 默认值 描述
    debug false
    显性关闭连接失败时输出警告
    error false
    显性关闭连接失败时抛出异常

过程 21.1. 用管理控制台配置 JCA 子系统

  1. JBoss EAP 6 的 JCA 子系统可以在管理控制台里进行配置。根据服务器运行的方式,JCA 配置选项在管理控制台里所处的位置会有轻微的不同。
    • 如果服务器作为独立服务器运行,请遵循下列步骤:
      1. 点击右上角的 Profile 链接切换至 Profile 视图。
      2. 确保展开左侧导航面板的 Profile 部分。
      3. 点击 Connector 展开它并点击 JCA
    • 如果服务器是作为受管域的一部分运行,请遵循下列步骤:
      1. 点击右上角的 Profile 链接切换至 Profile 视图。
      2. 从左侧导航面板的顶部的 Profile 菜单里选择您要修改的配置集。
      3. 点击 Connector 展开它并点击 JCA
  2. 用下列三个标签页配置 JCA 子系统。
    1. Common Config

      Common Config 标签页包含每个缓存连接管理者、归档检验和 Bean 检验(JSR-303)的设置。这些设置都包含在自己的标签页里。您可以打开合适的标签页并点击 Edit 按钮,进行所需修改后再 Save 按钮保存。
      JCA 的常见配置

      图 21.1. JCA 的常见配置

    2. Work Managers

      Work Manager 标签页包含配置的 Work Manager 的列表。您可以新建、删除 Work Manager 以及配置线程池。每个 Work Manager 都可以有一个短期运行以及一个长期运行的的线程池。
      Work Managers

      图 21.2. Work Managers

      线程池的属性可以在这里配置:
      Work Manager 的线程池

      图 21.3. Work Manager 的线程池

    3. Bootstrap Contexts

      Bootstrap Contexts 标签页包含了 Bootstrap Contexts 列表。您可以创建、删除和配置 Bootstrap Context。每个 Bootstrap Context 都必须分配一个 Work Manager。
      Bootstrap Contexts

      图 21.4. Bootstrap Contexts

21.3. 部署资源适配器

资源适配器可以用管理 CLI 工具、基于 Web 的管理控制台或手动复制文件的方式部署到 JBoss EAP 6。这个过程和其他可部署的 Artifact 是一样的。

过程 21.2. 用管理 CLI 部署资源适配器

  1. 在你的操作系统里打开一个命令行提示窗口。
  2. 连接至管理 CLI。
    • 对于 Linux,输入下列命令:
      $ EAP_HOME/bin/jboss-cli.sh --connect
      $ Connected to standalone controller at localhost:9999
      
    • 对于 Windows,输入下列命令:
      C:\>EAP_HOME\bin\jboss-cli.bat --connect
      C:\> Connected to standalone controller at localhost:9999
      
  3. 部署资源适配器。
    • 要部署资源适配器到独立服务器,请输入下列命令:
      $ deploy path/to/resource-adapter-name.rar
    • 要部署资源适配器到受管域里的所有服务器组,请输入下列命令:
      $ deploy path/to/resource-adapter-name.rar --all-server-groups
      

过程 21.3. 用基于 Web 的管理控制台部署资源适配器

  1. 启动 JBoss EAP 6 服务器。
  2. 如果您还没有添加管理用户,请现在就添加。详情请参考《JBoss EAP 6 安装指南》里的『Getting Started』章节。 第 4.1.1 节 “为管理接口添加用户”
  3. 打开 Web 浏览器并导航至管理控制台。默认的位置是 http://localhost:9990/console/。关于管理控制台的更多信息,请参考 第 3.4.2 节 “登录到管理控制台”
  4. 点击右上角的 Runtime 链接切换到 Runtime 视图,然后选择左侧导航面板上的 Manage Deployments,再点击右上角的 Add Content
  5. 浏览资源适配器并选择它。然后点击 Next
  6. 验证部署名称,然后点击 Save
  7. 资源适配器归档应该出现在列表里且状态为禁用的。点击 Enable 链接启用它。
  8. "Are you sure?" 对话框会出现询问是否启用列出的 RAR。请点击 Confirm。资源适配器归档应该显示为 Enabled

过程 21.4. 手动部署资源适配器

  • 复制资源适配器归档到服务器的部署目录,
    • 对于独立服务器,复制资源适配器归档到 EAP_HOME/standalone/deployments/ 目录。
    • 对于受管域,复制资源适配器归档到域控制器的 EAP_HOME/domain/deployments/

21.4. 配置已部署的资源适配器

JBoss 管理员可以用管理 CLI 工具、基于 Web 的管理控制台或手动编辑配置文件的方式来配置资源适配器。
关于所支持的属性和其他细节,请参考资源适配器的相关文档。

注意

在下面的过程里,请在 [standalone@localhost:9999 /] 提示符后输入命令行。请不要输入花括号里的内容。这是命令执行的结果,例如 {"outcome" => "success"}

过程 21.5. 用管理 CLI 配置资源适配器

  1. 在你的操作系统里打开一个命令行提示窗口。
  2. 连接至管理 CLI。
    • 对于 Linux,输入下列命令:
      $ EAP_HOME/bin/jboss-cli.sh --connect
      
      您应该看到下列输出结果:
      $ Connected to standalone controller at localhost:9999
      
    • 对于 Windows,输入下列命令:
      C:\>EAP_HOME\bin\jboss-cli.bat --connect
      
      您应该看到下列输出结果:
      C:\> Connected to standalone controller at localhost:9999
      
  3. 添加资源适配器配置。
    [standalone@localhost:9999 /] /subsystem=resource-adapters/resource-adapter=eis.rar:add(archive=eis.rar, transaction-support=XATransaction) 
    {"outcome" => "success"}
    
  4. 配置 server 资源适配器级别 <config-property>。
    [standalone@localhost:9999 /] /subsystem=resource-adapters/resource-adapter=eis.rar/config-properties=server/:add(value=localhost)          
    {"outcome" => "success"}
    
  5. 配置 port 资源适配器级别 <config-property>。
    [standalone@localhost:9999 /] /subsystem=resource-adapters/resource-adapter=eis.rar/config-properties=port/:add(value=9000)
    {"outcome" => "success"}
    
  6. 为受管连接工厂添加连接定义。
    [standalone@localhost:9999 /] /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName:add(class-name=com.acme.eis.ra.EISManagedConnectionFactory, jndi-name=java:/eis/AcmeConnectionFactory)
    {"outcome" => "success"}
    
  7. 配置 name 受管连接工厂级别的 <config-property>。
    [standalone@localhost:9999 /] /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName/config-properties=name/:add(value=Acme Inc)
    {"outcome" => "success"}
    
  8. 添加 admin 对象。
    [standalone@localhost:9999 /] /subsystem=resource-adapters/resource-adapter=eis.rar/admin-objects=aoName:add(class-name=com.acme.eis.ra.EISAdminObjectImpl, jndi-name=java:/eis/AcmeAdminObject)
    {"outcome" => "success"}
    
  9. 配置 Admin 对象的 threshold 属性。
    [standalone@localhost:9999 /] /subsystem=resource-adapters/resource-adapter=eis.rar/admin-objects=aoName/config-properties=threshold/:add(value=10)
    {"outcome" => "success"}
    
  10. 激活资源适配器。
    [standalone@localhost:9999 /] /subsystem=resource-adapters/resource-adapter=eis.rar:activate
    {"outcome" => "success"}
    
  11. 查看最新配置和激活的资源适配器。
    [standalone@localhost:9999 /] /subsystem=resource-adapters/resource-adapter=eis.rar:read-resource(recursive=true)
    {
        "outcome" => "success",
        "result" => {
            "archive" => "eis.rar",
            "beanvalidationgroups" => undefined,
            "bootstrap-context" => undefined,
            "transaction-support" => "XATransaction",
            "admin-objects" => {"aoName" => {
                "class-name" => "com.acme.eis.ra.EISAdminObjectImpl",
                "enabled" => true,
                "jndi-name" => "java:/eis/AcmeAdminObject",
                "use-java-context" => true,
                "config-properties" => {"threshold" => {"value" => 10}}
            }},
            "config-properties" => {
                "server" => {"value" => "localhost"},
                "port" => {"value" => 9000}
            },
            "connection-definitions" => {"cfName" => {
                "allocation-retry" => undefined,
                "allocation-retry-wait-millis" => undefined,
                "background-validation" => false,
                "background-validation-millis" => undefined,
                "blocking-timeout-wait-millis" => undefined,
                "class-name" => "com.acme.eis.ra.EISManagedConnectionFactory",
                "enabled" => true,
                "flush-strategy" => "FailingConnectionOnly",
                "idle-timeout-minutes" => undefined,
                "interleaving" => false,
                "jndi-name" => "java:/eis/AcmeConnectionFactory",
                "max-pool-size" => 20,
                "min-pool-size" => 0,
                "no-recovery" => undefined,
                "no-tx-separate-pool" => false,
                "pad-xid" => false,
                "pool-prefill" => false,
                "pool-use-strict-min" => false,
                "recovery-password" => undefined,
                "recovery-plugin-class-name" => undefined,
                "recovery-plugin-properties" => undefined,
                "recovery-security-domain" => undefined,
                "recovery-username" => undefined,
                "same-rm-override" => undefined,
                "security-application" => undefined,
                "security-domain" => undefined,
                "security-domain-and-application" => undefined,
                "use-ccm" => true,
                "use-fast-fail" => false,
                "use-java-context" => true,
                "use-try-lock" => undefined,
                "wrap-xa-resource" => true,
                "xa-resource-timeout" => undefined,
                "config-properties" => {"name" => {"value" => "Acme Inc"}}
            }}
        }
    }
    

过程 21.6. 用基于 Web 的管理控制台配置资源适配器

  1. 启动 JBoss EAP 6 服务器。
  2. 如果您还没有添加管理用户,请现在就添加。详情请参考《JBoss EAP 6 安装指南》里的『Getting Started』章节。
  3. 打开 Web 浏览器并导航至管理控制台。默认的位置是 http://localhost:9990/console/。关于管理控制台的更多信息,请参考 第 3.4.2 节 “登录到管理控制台”
  4. 点击 Profile 链接切换至 Profile 视图。在导航面板里选择 Resource Adapters,然后点击 Add
  5. 输入归档名称并从 TX: 下拉框里选择事务类型 XATransaction。然后点击 Save
  6. 选择 Properties 标签页,然后点击 Add 来添加资源适配器属性。
  7. Name 和主机名里输入 server,例如在 Save 里输入 localhost。然后点击 Save 保存属性。
  8. Name 和主机名里输入 port,例如在 Save 里输入 9000。然后点击 Save 保存属性。
  9. serverport 属性现在出现在 Properties 面板里。点击列出的资源适配器的 Option 列下的 View 链接来查看 Connection Definitions
  10. 点击页面右上角的 Add 按钮来添加连接定义。
  11. 输入 Connection ClassJNDI Name 和全限定类名。然后点击 Next
  12. 点击 Add 后输入这个连接定义的 KeyValue 数据。
  13. 点击 Key 栏目下的 name 字段来启用数据输入。输入属性名称并在完成后按 Enter。点击 Value 栏目下的 value 字段来启用数据输入。输入属性名称并在完成后按 Enter。然后点击 Save 保存属性。
  14. 连接定义已完成,但却是禁用的。请点击 Enable 启用它。
  15. "Really modify Connection Definition?" 对话框会出现询问是否进行修改。请点击 Confirm。连接定义现在应该显示为 Enabled
  16. 点击页面正上方的 Admin Objects 标签来创建和配置 admin 对象。然后点击 Add 按钮。
  17. 输入 admin 对象的 JNDI Name 和全限定的 Class Name。然后点击 Save
  18. 选择 Properties 标签页,然后点击 Add 来添加 admin 对象的属性。
  19. Name 字段里输入一个 admin 对象配置属性,例如 threshold。在 Value 字段里输入属性值,如 10。然后点击 Save 保存属性。
  20. admin 对象已完成,但却是禁用的。请点击 Enable 启用它。
  21. "Really modify Admin Ojbect?" 对话框会出现询问是否进行修改。请点击 Confirm。admin 对象现在应该显示为 Enabled
  22. 您必需重载服务器配置来完成这个过程。点击 Runtime 视图上的 Runtime 链接,然后选择左侧导航面板上的 Configuration,并点击 Reload
  23. "Do you want to reload the server configuration?" 对话框会出现询问是否进行重载。请点击 Confirm。服务器配置现在是最新版本了。

过程 21.7. 手动配置资源适配器

  1. 停止 JBoss EAP 6 服务器。

    重要

    要使修改在服务器重启后仍然生效,你必须在编辑服务器配置文件前停止服务器。
  2. 打开服务器配置文件进行编辑。
    • 对于独立服务器,这个文件是 EAP_HOME/standalone/configuration/standalone.xml
    • 对于受管域,这个文件是 EAP_HOME/domain/configuration/domain.xml
  3. 在配置文件里找到 urn:jboss:domain:resource-adapters 子系统。
  4. 如果没有为这个子系统定义资源适配器,请首先替换:
    <subsystem xmlns="urn:jboss:domain:resource-adapters:1.1"/>
    
    
    
    使用下列内容:
                      
    
    <subsystem xmlns="urn:jboss:domain:resource-adapters:1.1">
        <resource-adapters>
            <!-- <resource-adapter> configuration listed below -->
        </resource-adapters>
    </subsystem>
    
    
    
  5. 用您的资源适配器的 XML 定义替换 <!-- <resource-adapter> configuration listed below -->。下面是用管理 CLI 和基于 Web 的管理控制台创建的资源适配器配置的 XML 片段。
    <resource-adapter>
        <archive>
            eis.rar
        </archive>
        <transaction-support>XATransaction</transaction-support>
        <config-property name="server">
            localhost
        </config-property>
        <config-property name="port">
            9000
        </config-property>
        <connection-definitions>
            <connection-definition class-name="com.acme.eis.ra.EISManagedConnectionFactory" 
                    jndi-name="java:/eis/AcmeConnectionFactory"
                    pool-name="java:/eis/AcmeConnectionFactory">
                <config-property name="name">
                    Acme Inc
                </config-property>
            </connection-definition>
        </connection-definitions>
        <admin-objects>
            <admin-object class-name="com.acme.eis.ra.EISAdminObjectImpl" 
                    jndi-name="java:/eis/AcmeAdminObject" 
                    pool-name="java:/eis/AcmeAdminObject">
                <config-property name="threshold">
                    10
                </config-property>
            </admin-object>
        </admin-objects>
    </resource-adapter>
    
    
    
  6. 启动服务器

    重新启动 JBoss EAP 6 服务器以使用新的配置运行。

21.5. 资源适配器描述符参考

下表描述了资源适配器描述符文件的元素。
Expand
表 21.7. 主要元素
描述
bean-validation-groups 指定应该使用的 Bean 检验组
bootstrap-context 指定应该使用的引导上下文的唯一名称。
config-property 指定资源适配器的配置属性。
transaction-support 定义这个资源适配器支持的事务类型。有效的值为:NoTransaction、LocalTransaction 和 XATransaction。
connection-definitions 指定连接定义
admin-objects 指定管理对象
Expand
表 21.8. Bean 检验组元素
描述
bean-validation-group 指定用于检验的 Bean 检验组的全限定类名
Expand
表 21.9. 连接定义 / Admin 对象的属性
属性 描述
class-name 指定受管连接工厂或 Admin 对象的全限定类名。
jndi-name 指定 JNDI 名称
enabled 对象是否被激活
use-java-context 指定是否使用 java:/ JNDI 上下文
pool-name 指定对象的池名
use-ccm 启用缓存的连接管理者
Expand
表 21.10. 连接定义元素
描述
config-property 指定受管连接工厂的配置属性。
pool 指定池的设置
xa-pool 指定 XA 池的设置
security 指定安全设置
timeout 指定超时设置
validation 指定检验设置
recovery 指定 XA 恢复设置
Expand
表 21.11. 池元素
描述
min-pool-size 指定池应该保持的连接的最小数目。在连接的请求主题知晓之前,这些连接不会被创建。默认值是 0。
max-pool-size 指定某个池的连接的最大数目。每个子池里不会创建超过 max-pool-size 个连接。默认值是 20。
prefill 是否预填充连接池。默认值是 False。
use-strict-min 指定是否严格考虑 min-pool-size。默认值为 false。
flush-strategy 指定在发生错误时如何冲刷池。有效值为:FailingConnectionOnly (默认值)、IdleConnections、EntirePool。
Expand
表 21.12. XA 池元素
描述
min-pool-size 指定池应该保持的连接的最小数目。在连接的请求主题知晓之前,这些连接不会被创建。默认值是 0。
max-pool-size 指定某个池的连接的最大数目。每个子池里不会创建超过 max-pool-size 个连接。默认值是 20。
prefill 是否预填充连接池。默认值是 False。
use-strict-min 指定是否严格考虑 min-pool-size。默认值为 false。
flush-strategy 指定在发生错误时如何冲刷池。有效值为:FailingConnectionOnly (默认值)、IdleConnections、EntirePool。
is-same-rm-override is-same-rm-override 元素允许您无条件地设置 javax.transaction.xa.XAResource.isSameRM(XAResource) 返回 true 或 false。
interleaving 为 XA 连接工厂启用 interleaving 的元素
no-tx-separate-pools Oracle 不允许既在 JTA 事务内部又在外部使用 XA 连接。变通办法是为不同的上下文创建单独的子池。
pad-xid 是否保护(Pad)XID
wrap-xa-resource 是否将 XAResource 实例包裹在 org.jboss.tm.XAResourceWrapper 实例里
Expand
表 21.13. 安全元素
描述
application 指定应用程序提供的参数(如来自 getConnection(user, pw))是否可用于区分池里的连接。
security-domain 指定用于区分池里连接的主题(来自安全域)。security-domain 的内容是处理验证的 JAAS 安全管理者的名称。这个名称和 JAAS login-config.xml 的 application-policy/name 属性是关联的。
security-domain-and-application 指定用于区分池里连接的应用程序参数(如来自 getConnection(user, pw))或主题(来自安全域)。security-domain 的内容是处理验证的 JAAS 安全管理者的名称。这个名称和 JAAS login-config.xml 的 application-policy/name 属性是关联的。
Expand
表 21.14. 超时元素
描述
blocking-timeout-millis 指定在抛出异常前等待连接时阻塞的最长时间。请注意,这只是等待连接许可时的阻塞,如果创建连接时超时并不会抛出异常。默认值是 30000(30 秒)。
idle-timeout-minutes 指定连接在被关闭前最长的空闲时间。实际的最长时间也取决于 IdleRemover 扫描时间,它是所有池里最小的 idle-timeout-minutes 的二分之一。
allocation-retry 指定在抛出异常前尝试分配连接的次数。默认值为 0。
allocation-retry-wait-millis 指定试图分配连接时重试的间隔(毫秒)。默认值是 5000(5 秒)。
xa-resource-timeout 传递给 XAResource.setTransactionTimeout() 的参数。默认为 0,表示不调用 setter。其单位为秒。
Expand
表 21.15. 检验元素
描述
background-validation 指定这个连接在使用前应该通过后台线程进行检验。
background-validation-minutes background-validation-minutes 元素
use-fast-fail 在第一次尝试时如果连接无效则失败(true)、或者一直尝试直至遍历连接池里所有连接(false)。默认为 false。
Expand
表 21.16. Admin 对象的元素
描述
config-property 指定管理对象的配置属性。
Expand
表 21.17. 恢复元素
描述
recover-credential 指定应用于恢复的用户名/密码或安全域。
recover-plugin 指定 org.jboss.jca.core.spi.recovery.RecoveryPlugin 类的实现。
定义在 jboss-as-resource-adapters_1_0.xsd 里的部署模式以及用于自动激活的 http://www.ironjacamar.org/doc/schema/ironjacamar_1_0.xsd

21.6. 查看定义的连接统计

您可以在 deployment=name.rar 子树里查看定义连接的统计信息。
统计信息在这个级别而不是 /subsystem 级别来定义是为了确保可以被没有在 standalone.xmldomain.xml 文件里的任何配置里定义的 rar 访问。
例如:

例 21.1. 

/deployment=example.rar/subsystem=resource-adapters/statistics=statistics/connection-definitions=java\:\/testMe:read-resource(include-runtime=true)

注意

请确保您指定了 include-runtime=true 参数,因为所有的统计信息都是运行时信息。默认值为 false

21.7. 资源适配器的统计信息

核心统计信息

下表包含了所支持的资源适配器核心统计信息:

Expand
表 21.18. 核心统计信息
名称 描述
ActiveCount
活动连接的数量。这些是正在使用的连接、或者是连接池里可用的连接。
AvailableCount
池里可用连接的数量。
AverageBlockingTime
获取池的排斥锁的平均阻塞时间。这个值的单位是毫秒。
AverageCreationTime
创建连接的平均时间。这个值的单位是毫秒。
CreatedCount
创建的连接的数量。
DestroyedCount
销毁的连接的数量。
InUseCount
正在使用的连接的数量。
MaxCreationTime
创建连接所需的最长时间。这个值的单位是毫秒。
MaxUsedCount
使用的连接的最大数量。
MaxWaitCount
同时等待连接的请求的最大数量。
MaxWaitTime
等待连接池里排他锁所花费的最长时间。
TimedOut
超时连接的数量。
TotalBlockingTime
等待连接池里排他锁总共所花费的时间。单位为毫秒。
TotalCreationTime
创建连接总共所花费的时间。单位为毫秒。
WaitCount
需要等待连接的请求的数量。

21.8. 部署 WebSphere MQ 资源适配器

关于 WebSphere MQ

WebSphere MQ 是 IBM 的面向消息中间件(Messaging Oriented Middleware,MOM),它允许分布式系统上的应用程序彼此通讯。这是通过消息和消息队列来实现的。WebSphere MQ 负责递送消息到消息队列并用消息频道传输数据到其他队列管理者。关于 WebSphere MQ 的更多信息,请参考 WebSphere MQ

概述

本节涵盖在 JBoss EAP 6 里部署和配置 WebSphere MQ 资源适配器的步骤。您可以手动编辑配置文件来完成,也可以通过管理 CLI 或使用基于 Web 的管理控制台来完成。

前提条件

在开始之前,您必需检验 WebSphere MQ 资源适配器的版本并理解一些 WebSphere MQ 配置属性。

  • WebSphere MQ 资源适配器是作为 Resource Archive (RAR) 文件(wmq.jmsra-VERSION.rar)提供的。您必须使用 7.0.1.7 或之后的版本。
  • 您必须了解下列 WebSphere MQ 配置属性。关于这些属性的细节,请参考 WebSphere MQ 产品文档。
    • MQ.QUEUE.MANAGER:WebSphere MQ 队列管理者的名称
    • MQ.PORT:用来连接 WebSphere MQ 队列管理者的主机名
    • MQ.PORT:用来连接 WebSphere MQ 队列管理者的服务器频道
    • MQ.QUEUE.NAME:目标队列的名称
    • MQ.PORT:用来连接 WebSphere MQ 队列管理者的端口
    • MQ.CLIENT:传输类型
  • 对于转出连接,您也必须熟悉下列配置属性:
    • MQ.CONNECTIONFACTORY.NAME:提供连接给远程系统的连接工厂实例的名称

注意

下面是 IBM 提供的默认配置,您可以根据需要进行修改。更多信息请参考 WebSphere MQ 文档。

过程 21.8. 手动部署资源适配器

  1. 如果您需要 WebSphereMQ 资源适配器支持事务,您必须重新打包 wmq.jmsra-VERSION.rar 归档,使其包含 mqetclient.jar。您可以使用下列命令:
    [user@host ~]$ jar -uf wmq.jmsra-VERSION.rar mqetclient.jar
    请用正确的版本号码替换 VERSION
  2. 复制 wmq.jmsra-VERSION.rar 文件到 EAP_HOME/standalone/deployments/ 目录。
  3. 在服务器配置文件里添加资源适配器。
    1. 在编辑器里打开 EAP_HOME/standalone/configuration/standalone-full.xml 文件。
    2. 在配置文件里找到 urn:jboss:domain:resource-adapters 子系统。
    3. 如果这个子系统没有定义资源适配器,请替换:
      <subsystem xmlns="urn:jboss:domain:resource-adapters:1.1"/>
      
      
      
      为:
                        
      
      <subsystem xmlns="urn:jboss:domain:resource-adapters:1.1">
          <resource-adapters>
              <!-- <resource-adapter> configuration listed below -->
          </resource-adapters>
      </subsystem>
      
      
      
    4. 资源适配器的配置依赖您是否需要事务支持和恢复。如果您不需要事务支持,请选择下面的第一个配置步骤。如果您需要事务支持,请选择第二个配置步骤。
      • 对于非事务性部署,请用下列内容替换 <!-- <resource-adapter> configuration listed below -->
        <resource-adapter>
            <archive>
                wmq.jmsra-VERSION.rar
            </archive>
            <transaction-support>NoTransaction</transaction-support>
            <connection-definitions>
                <connection-definition 
                        class-name="com.ibm.mq.connector.outbound.ManagedConnectionFactoryImpl" 
                        jndi-name="java:jboss/MQ.CONNECTIONFACTORY.NAME" 
                        pool-name="MQ.CONNECTIONFACTORY.NAME">
                    <config-property name="channel">
                        MQ.CHANNEL.NAME
                    </config-property>
                    <config-property name="transportType">
                        MQ.CLIENT
                    </config-property>
                    <config-property name="queueManager">
                        MQ.QUEUE.MANAGER
                    </config-property>
                    <security>
                        <security-domain>MySecurityDomain</security-domain>
                    </security>
               </connection-definition>
            </connection-definitions>
            <admin-objects>
                <admin-object 
                        class-name="com.ibm.mq.connector.outbound.MQQueueProxy" 
                        jndi-name="java:jboss/MQ.QUEUE.NAME" 
                        pool-name="MQ.QUEUE.NAME">
                    <config-property name="baseQueueName">
                        MQ.QUEUE.NAME
                    </config-property>
                </admin-object>
            </admin-objects>
        </resource-adapter>
        
        
        
        请确保用 RAR 名称里的实际版本替换 VERSION
      • 对于事务性部署,请用下列内容替换 <!-- <resource-adapter> configuration listed below -->
        <resource-adapter>
            <archive>
                wmq.jmsra-VERSION.rar
            </archive>
            <transaction-support>XATransaction</transaction-support>
            <connection-definitions>
                <connection-definition 
                        class-name="com.ibm.mq.connector.outbound.ManagedConnectionFactoryImpl" 
                        jndi-name="java:jboss/MQ.CONNECTIONFACTORY.NAME" 
                        pool-name="MQ.CONNECTIONFACTORY.NAME">
                    <config-property name="channel">
                        MQ.CHANNEL.NAME
                    </config-property>
                    <config-property name="transportType">
                        MQ.CLIENT
                    </config-property>
                    <config-property name="queueManager">
                        MQ.QUEUE.MANAGER
                    </config-property>
                   <security>
                        <security-domain>MySecurityDomain</security-domain>
                    </security>
                    <recovery>
                        <recover-credential>
                            <user-name>USER_NAME</user-name>
                            <password>PASSWORD</password>
                        </recover-credential>
                    </recovery>
                </connection-definition>
            </connection-definitions>
            <admin-objects>
                <admin-object 
                        class-name="com.ibm.mq.connector.outbound.MQQueueProxy" 
                        jndi-name="java:jboss/MQ.QUEUE.NAME" 
                        pool-name="MQ.QUEUE.NAME">
                    <config-property name="baseQueueName">
                        MQ.QUEUE.NAME
                    </config-property>
                </admin-object>
            </admin-objects>
        </resource-adapter>
        
        
        
        请确保用 RAR 名称里的实际版本替换 VERSION。您也必须用有效的用户名和密码替换 USER_NAMEPASSWORD

        注意

        为了支持事务, <transaction-support> 元素要设置为 XATransaction。为了支持 XA 恢复,<recovery> 元素要添加至连接定义里。
    5. 如果您想将 JBoss EAP 6 里的默认 EJB3 消息系统 HornetQ 修改为 WebSphere MQ,请这样修改 urn:jboss:domain:ejb3:1.2 子系统:
      替换:
      <mdb>
          <resource-adapter-ref resource-adapter-name="hornetq-ra"/>
          <bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>
      </mdb>
      
      
      
      为:
      <mdb>
          <resource-adapter-ref resource-adapter-name="wmq.jmsra-VERSION.rar"/>
          <bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>
      </mdb>
      
      
      
      请确保用 RAR 名称里的实际版本替换 VERSION

过程 21.9. 修改 MDB 代码来使用资源适配器

  • 在 MDB 代码里这样配置 ActivationConfigProperty 和 ResourceAdapter
    @MessageDriven( name="WebSphereMQMDB", 
        activationConfig =
        {
            @ActivationConfigProperty(propertyName = "destinationType",propertyValue = "javax.jms.Queue"),
            @ActivationConfigProperty(propertyName = "useJNDI", propertyValue = "false"),
            @ActivationConfigProperty(propertyName = "hostName", propertyValue = "MQ.HOST.NAME"),
            @ActivationConfigProperty(propertyName = "port", propertyValue = "MQ.PORT"),
            @ActivationConfigProperty(propertyName = "channel", propertyValue = "MQ.CHANNEL.NAME"),
            @ActivationConfigProperty(propertyName = "queueManager", propertyValue = "MQ.QUEUE.MANAGER"),
            @ActivationConfigProperty(propertyName = "destination", propertyValue = "MQ.QUEUE.NAME"),
            @ActivationConfigProperty(propertyName = "transportType", propertyValue = "MQ.CLIENT")
        })
        @ResourceAdapter(value = "wmq.jmsra-VERSION.rar")
    @TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED)
    public class WebSphereMQMDB implements MessageListener {
    }
    
    请确保用 RAR 名称里的实际版本替换 VERSION
概述

您可以配置 JBoss EAP 6 和第三方的 JMS 供应商一起使用,然而不是所有的 JMS 供应商都为集成 Java 应用程序而编写 JMS JCA 资源适配器。这个过程涵盖了配置 JBoss EAP 6 里包含的通用 JMS 资源适配器来连接 JMS 供应商的步骤。在这个过程里,Tibco EMS 6.3 用作示例 JMS 供应商,其他的 JMS 供应商需要不同的配置。

重要

通用 JMS JCA 资源适配器只应该在 JMS 供应商没有提供自己的资源适配器时才使用。在使用通用 JMS 资源适配器之前,您应该首先检查 JMS 供应商是否有可用于 JBoss EAP 6 的自己的资源适配器。
前提条件

这个过程假设 JMS 供应商服务器已配置好并已准备好运行。您需要准备这个供应商的 JMS 实现所需的任何二进制文件。您也需要知道下列 JMS 供应商属性的值:

  • PROVIDER_HOST:PROVIDER_PORT:JMS 供应商服务器的主机名和端口号。
  • PROVIDER_CONNECTION_FACTORY:JMS 供应商上连接工厂的名称。
  • PROVIDER_QUEUE, PROVIDER_TOPIC:要使用的 JMS 供应商的队列和主题的名称。

过程 21.10. 配置通用 JMS 资源适配器

  1. 为队列和主题的 JNDI 绑定创建一个 ObjectFactory 实现:
    1. 将下列内容作为模版,用您自己的 JMS 供应商服务器的值替换服务器细节。
      import java.util.Hashtable;
      import java.util.Properties;
       
      public class RemoteJMSObjectFactory implements ObjectFactory {
       
        private Context context = null;
       
        public RemoteJMSObjectFactory() {
        }
       
        public Object getObjectInstance(Object obj, Name name, Context nameCtx,
            Hashtable<?, ?> environment) throws Exception {
          try {
            String jndi = (String) obj;
       
            final Properties env = new Properties();
            env.put(Context.INITIAL_CONTEXT_FACTORY,
                "com.tibco.tibjms.naming.TibjmsInitialContextFactory");
            env.put(Context.URL_PKG_PREFIXES, "com.tibco.tibjms.naming");
            env.put(Context.PROVIDER_URL, "tcp://TIBCO_HOST:TIBCO_PORT");
       
            context = new InitialContext(env);
            Object o = context.lookup(jndi);
       
            return o;
          } catch (NamingException e) {
            e.printStackTrace();
            throw e;
          }
        }
      }
      
    2. 编译上面的代码,并将生成的类文件保存在 remoteJMSObjectFactory.jar 里。
  2. 为你的 JBoss EAP 6 实例创建一个 genericjms 模块:
    1. 创建下列目录结构:EAP_HOME/modules/system/layers/base/org/jboss/genericjms/provider/main
    2. 复制 remoteJMSObjectFactory.jar 文件到 EAP_HOME/modules/system/layers/base/org/jboss/genericjms/provider/main
    3. Copy the binaries required for the provider's JMS implementation to EAP_HOME/modules/system/layers/base/org/jboss/genericjms/provider/main. For Tibco EMS, the binaries required are tibjms.jar and tibcrypt.jar from the Tibco installation's /lib directory.
    4. EAP_HOME/modules/system/layers/base/org/jboss/genericjms/provider/main 里创建一个 module.xml 文件,将之前步骤里的 JAR 文件列为资源:
      <module xmlns="urn:jboss:module:1.1" name="org.jboss.genericjms.provider"> 
        <resources> 
            <resource-root path="tibjms.jar"/> 
            <resource-root path="tibcrypt.jar"/>
            <resource-root path="remoteJMSObjectFactory.jar"/>
        </resources> 
      
         <dependencies> 
            <module name="javax.api"/> 
            <module name="javax.jms.api"/> 
        </dependencies> 
      </module>
      
  3. 通过全局模块的方式将通用 JMS 模块添加为所有部署的依赖关系。

    注意

    在这个过程里,EAP_HOME/standalone/configuration/standalone-full.xml 被用作 JBoss EAP 6 配置文件。
    EAP_HOME/standalone/configuration/standalone-full.xml<subsystem xmlns="urn:jboss:domain:ee:1.1"> 下添加:
    <global-modules>
      <module name="org.jboss.genericjms.provider" slot="main"/>
      <module name="org.jboss.common-core" slot="main"/>
    </global-modules>
    
  4. 用通用的资源适配器替换默认的 HornetQ 资源适配器。
    EAP_HOME/standalone/configuration/standalone-full.xml 里,下列内容替换 <subsystem xmlns="urn:jboss:domain:ejb3:1.4"> <mdb>
    <mdb>
      <resource-adapter-ref resource-adapter-name="org.jboss.genericjms"/>
      <bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>
    </mdb>
    
  5. 因为远程对象是必需的,请为您的 JMS 主题和队列添加绑定。
    EAP_HOME/standalone/configuration/standalone-full.xml 里的 <subsystem xmlns="urn:jboss:domain:naming:1.3"> 下,添加绑定,并按需要替换 PROVIDER_QUEUEPROVIDER_TOPIC
    <bindings>
      <object-factory name="PROVIDER_QUEUE" module="org.jboss.genericjms.provider" class="org.jboss.qa.RemoteJMSObjectFactory"/>
      <object-factory name="PROVIDER_TOPIC" module="org.jboss.genericjms.provider" class="org.jboss.qa.RemoteJMSObjectFactory"/>
    </bindings>
    
  6. EAP_HOME/standalone/configuration/standalone-full.xml 里,添加通用资源适配器配置到 <subsystem xmlns="urn:jboss:domain:resource-adapters:1.1">
    用 JMS 供应商的值替换 PROVIDER_CONNECTION_FACTORYPROVIDER_HOSTPROVIDER_PORT
    <resource-adapters>
      <resource-adapter id="org.jboss.genericjms">
        <module slot="main" id="org.jboss.genericjms"/>
        <transaction-support>NoTransaction</transaction-support>
        <connection-definitions>
          <connection-definition class-name="org.jboss.resource.adapter.jms.JmsManagedConnectionFactory" jndi-name="java:/jms/PROVIDER_CONNECTION_FACTORY" pool-name="PROVIDER_CONNECTION_FACTORY">
            <config-property name="JndiParameters">
              java.naming.factory.initial=com.tibco.tibjms.naming.TibjmsInitialContextFactory;java.naming.provider.url=tcp://PROVIDER_HOST:PROVIDER_PORT
            </config-property>
            <config-property name="ConnectionFactory">
              PROVIDER_CONNECTION_FACTORY
            </config-property>
            <security>
              <application/>
            </security>
          </connection-definition>
        </connection-definitions>
      </resource-adapter>
    </resource-adapters>
    
结果

配置了通用的 JMS 资源适配器以供使用。

当创建新的 Message Driven Bean(MDB)时,请用类似下面的代码来使用资源适配器。用 JMS 供应商的值来替换 PROVIDER_CONNECTION_FACTORYPROVIDER_HOSTPROVIDER_PORT
@MessageDriven(activationConfig = { 
  @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"), 
  @ActivationConfigProperty(propertyName = "jndiProperties", propertyValue = "java.naming.factory.initial=com.tibco.tibjms.naming.TibjmsInitialContextFactory;java.naming.provider.url=tcp://PROVIDER_HOST:PROVIDER_PORT")
  @ActivationConfigProperty(propertyName = "destination", propertyValue = "PROVIDER_QUEUE"), 
  @ActivationConfigProperty(propertyName = "connectionFactory", propertyValue = "PROVIDER_CONNECTION_FACTORY"),
})

@ResourceAdapter("generic-jms-ra.rar") 
public class SampleMdb implements MessageListener { 
  @Override

    public void onMessage(Message message) { 
    
    } 

}

第 22 章 在 Amazon EC2 上部署 JBoss EAP 6

22.1. 简介

22.1.1. 关于 Amazon EC2

Amazon Elastic Compute Cloud (Amazon EC2) 是 amazon.com 运行的一个服务,它为客户提供可定制的虚拟计算环境。Amazon Machine Image (AMI) 可以用这个服务引导来创建虚拟机或实例。用户可以在这个实例上安装任何他需要的软件,并根据使用情况来收费。Amazon EC2 的目的是允许用户快速扩充部署的应用程序及提供灵活性。
您可以在 Amazon EC2 的网站上了解详情:http://aws.amazon.com/ec2/

22.1.2. 关于 Amazon Machine Instance (AMI)

Amazon Machine Image (AMI) 是一个用于 EC2 虚拟机实例的模版。用户通过选择合适的 AMI 来创建 EC2 实例。AMI 的主要组件是一个只读的文件系统,它包含一个已安装的操作系统及其他软件。每个 AMI 都为不同的用例安装了不同的软件。Amazon EC2 包含了 amazon.com 和第三方提供的许多 AMI。用户也可以创建自己的 AMI。

22.1.3. 关于 JBoss Cloud Access

JBoss Cloud Access 是一个红帽的订阅功能,它提供对红帽认证的云基础结构供应商如 Amazon EC2 的支持。JBoss Cloud Access 允许您在传统服务器和基于云的公共资源以简单和高性价比的方式移动订阅。
您可以在这里找到更多细节:http://www.redhat.com/solutions/cloud/access/jboss/

22.1.4. JBoss Cloud Access 的功能

JBoss Cloud Access 计划的会员提过对 Red Hat 创建的私有 Amazon Machine Images (AMIs) 的访问。
Red Hat AMI 有下列预安装的软件且由 Red Hat 完全支持:
  • Red Hat 企业版 Linux 6
  • JBoss EAP 6
  • JBoss Operations Network (JON) 3 代理
  • 使用 Red Hat Update 基础结构的 RPM 产品更新。
每个 Red Hat AMI 都只是一个起点,要求进一步的配置来满足应用程序的需要。

重要

JBoss Cloud Access 目前不支持 full-ha 配置集,无论是独立实例还是受管域。

22.1.5. 支持的 Amazon EC2 实例类型

JBoss Cloud Access 支持下列 Amazon EC2 实例类型。关于每种实例类型的详情,请参考《Amazon EC2 用户指南》http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/instance-types.html
Expand
表 22.1. 支持的 Amazon EC2 实例类型
实例类型 描述
标准实例
标准实例(Standard Instance)是具有均衡的内存-CPU 比例的普通环境。
高内存实例
高内存实例(High Memory Instance)比标准实例分配了更多的内存。高内存实例适用于高吞吐量的应用程序,如数据库或用内存进行缓存的应用程序。
高 CPU 实例
高 CPU 实例(High CPU Instance)比高内存实例分配了更多的 CPU 资源,它适合较低的吞吐量但高度使用 CPU 的应用程序。

重要

实例类型 Micro (t1.micro) 不适合于 JBoss EAP 6 的部署。

22.1.6. 受支持的 Red Hat AMI

受支持的 Red Hat AMI 可以用 AMI 名称来标识。
JBoss EAP 6 AMI 使用下列语法来命名:
 RHEL-osversion-JBEAP-6.0.0-arch-creationdate 
osversion 是安装在 AMI 里的 Red Hat 企业版 Linux 的版本。例如:6.2
arch AMI 的架构。它是 x86_64i386
creationdate AMI 创建的日期,格式为 YYYYMMDD。例如 20120501
AMI 名称示例:RHEL-6.2-JBEAP-6.0.0-x86_64-20120501

22.2. 在 Amazon EC2 上部署 JBoss EAP 6

22.2.1. 在 Amazon EC2 上部署 JBoss EAP 6

JBoss EAP 6 可以用 Amazon EC2 AMI 进行部署。AMI 包含群集和非群集示例部署所需的一切元素。
部署非群集实例是最简单的情况。它只要求您在创建实例时修改一些配置来指定应用程序的部署。
部署群集实例复杂得多。除了群集实例外,您需要部署 JBoss EAP 6 实例来充当mod_cluster 代理以及 S3 Bucker 用于 S3_PING JGroups 发现协议。Red Hat 也推荐创建一个虚拟私有云来容纳您的群集。
下面详述了每个步骤,但也假定您具有相关的 JBoss EAP 6、Red Hat Enterprise Linux 6 和 Amazon EC2 的经验。
我们推荐参考下列文档:

22.2.2. 非群集的 JBoss EAP 6

22.2.2.1. 关于非群集的实例
非群集实例是运行 JBoss EAP 6 的单个 Amazon EC2 实例。它不是群集的一部分。
22.2.2.2. 非群集实例
22.2.2.2.1. 启动非群集的 JBoss EAP 6 实例
概述

本节涵盖在 Red Hat AMI(Amazon Machine Image)上启动 JBoss EAP 6 非群集实例的步骤。

前提条件

过程 22.1. 在 Red Hat AMI(Amazon Machine Image)上启动 JBoss EAP 6 非群集实例。

  1. 配置 User Data 字段。可配置的参数位于:第 22.4.1 节 “永久性的配置参数”第 22.4.2 节 “自定义脚本参数”

    例 22.1. “User Data” 字段示例

    这个例子展示了非群集 JBoss EAP 6 实例的“User Data” 字段。用户 admin 的密码已被设置为 adminpwd
    JBOSSAS_ADMIN_PASSWORD=adminpwd
    JBOSS_IP=0.0.0.0 #listen on all IPs and interfaces
    
    # In production, access to these ports needs to be restricted for security reasons
    PORTS_ALLOWED="9990 9443"
    
    cat> $USER_SCRIPT << "EOF"
    
    # Get the application to be deployed from an Internet URL
    # mkdir -p /usr/share/java/jboss-ec2-eap-applications
    # wget https://<your secure storage hostname>/<path>/<app name>.war -O /usr/share/java/jboss-ec2-eap-applications/<app name>.war 
    
    # Create a file of CLI commands to be executed after starting the server
    cat> $USER_CLI_COMMANDS << "EOC" 
    # deploy /usr/share/java/jboss-ec2-eap-applications/<app name>.war
    EOC
    
    EOF
    
    
  2. 对于产品实例

    对于产品实例,在 User Data 字段的 USER_SCRIPT 行下面添加下列内容,确保在引导时进行安全更新。
    yum -y update

    注意

    yum -y update 应该经常运行以应用安全修复和增强。
  3. 启动 Red Hat AMI 实例。
结果

已在 Red Hat AMI 上配置并启动 JBoss EAP 6 的非群集实例。

概述

本节涵盖在 Red Hat AMI 上的非群集 JBoss EAP 6 实例上部署应用程序。

    • 部署示例应用程序

      User Data 字段添加下列行:
      # Deploy the sample application from the local filesystem
      deploy --force /usr/share/java/jboss-ec2-eap-samples/hello.war
      

      例 22.2. 例程的『User Data』字段示例

      这个例子使用了 Red Hat AMI 提供的例程。它也包含了非群集 JBoss EAP 6 实例的基本配置。用户 admin 的密码已被设置为 adminpwd
      JBOSSAS_ADMIN_PASSWORD=adminpwd
      JBOSS_IP=0.0.0.0 #listen on all IPs and interfaces
      
      # In production, access to these ports needs to be restricted for security reasons
      PORTS_ALLOWED="9990 9443"
      
      cat> $USER_SCRIPT << "EOF"
      
      # Create a file of CLI commands to be executed after starting the server
      cat> $USER_CLI_COMMANDS << "EOC" 
      
      # Deploy the sample application from the local filesystem
      deploy --force /usr/share/java/jboss-ec2-eap-samples/hello.war
      EOC
      
      EOF
      
      
    • 部署自定义的应用程序

      User Data 字段添加下列行,配置应用程序名称和 URL:
      # Get the application to be deployed from an Internet URL
      mkdir -p /usr/share/java/jboss-ec2-eap-applications
      wget https://<your secure storage hostname>/<path>/<app name>.war -O /usr/share/java/jboss-ec2-eap-applications/<app name>.war
      
      

      例 22.3. 自定义应用程序的『User Data』字段示例

      这个例子使用了名为 MyApp 的应用程序,它也包含了非群集 JBoss EAP 6 实例的基本配置。用户 admin 的密码已被设置为 adminpwd
      JBOSSAS_ADMIN_PASSWORD=adminpwd
      JBOSS_IP=0.0.0.0 #listen on all IPs and interfaces
      
      # In production, access to these ports needs to be restricted for security reasons
      PORTS_ALLOWED="9990 9443"
      
      cat> $USER_SCRIPT << "EOF"
      
      # Get the application to be deployed from an Internet URL
      mkdir -p /usr/share/java/jboss-ec2-eap-applications
      wget https://PATH_TO_MYAPP/MyApp.war -O /usr/share/java/jboss-ec2-eap-applications/MyApp.war 
      
      # Create a file of CLI commands to be executed after starting the server
      cat> $USER_CLI_COMMANDS << "EOC" 
      deploy /usr/share/java/jboss-ec2-eap-applications/MyApp.war
      EOC
      
      EOF
      
      
  1. 启动 Red Hat AMI 实例。
结果

应用程序已成功部署到 JBoss EAP 6 里。

22.2.2.2.3. 测试非群集 JBoss EAP 6 实例
总结

本节涵盖了确认非群集 JBoss EAP 6 实例正确运行的步骤。

过程 22.2. 测试非群集 JBoss EAP 6 实例是否正确运行

  1. 确定实例的细节面板里的 Public DNS
  2. 进入 http://<public-DNS>:8080
  3. 确认 JBoss EAP 主页出现并包括到管理控制台的链接。如果主页不可用,请参考:第 22.5.1 节 “关于 Amazon EC2 的故障解除”
  4. 点击 Admin Console 链接。
  5. 登录:
  6. 测试例程

    访问 http://<public-DNS>:8080/hello 来测试例程是否已正确运行。文本 Hello World! 应该出现在浏览器里。如果没看到这个文本,请参考:第 22.5.1 节 “关于 Amazon EC2 的故障解除”
  7. 登出 JBoss EAP 6 管理控制台。
结果

JBoss EAP 6 实例已正确运行。

22.2.2.3. 非群集的受管域
22.2.2.3.1. 启动一个实例作为域控制器
概述

本节涵盖在 Red Hat AMI(Amazon Machine Image)上启动非群集 JBoss EAP 6 受管域的步骤。

过程 22.3. 在 Red Hat AMI(Amazon Machine Image)上启动非群集 JBoss EAP 6 受管域。

  1. 在 Security Group 标签页里,允许所有流量。如果需要的话用 Red Hat 企业版 Linux 的内置防火墙功能来限制访问。
  2. 设置 VPC 的公共子网为 running
  3. 选择一个静态 IP 地址。
  4. 配置 User Data 字段。可配置的参数位于:第 22.4.1 节 “永久性的配置参数”第 22.4.2 节 “自定义脚本参数”

    例 22.4. 『User Data』字段示例

    这个例子展示了非群集 JBoss EAP 6 受管域的“User Data” 字段。用户 admin 的密码已被设置为 adminpwd
    ## password that will be used by slave host controllers to connect to the domain controller
    JBOSSAS_ADMIN_PASSWORD=admin
    
    ## subnet prefix this machine is connected to
    SUBNET=10.0.0.
    
    #### to run the example no modifications below should be needed ####
    JBOSS_DOMAIN_CONTROLLER=true
    PORTS_ALLOWED="9999 9990 9443"
    JBOSS_IP=`hostname | sed -e 's/ip-//' -e 'y/-/./'` #listen on public/private EC2 IP address
    
    cat > $USER_SCRIPT << "EOF"
    ## Get the application to be deployed from an Internet URL
    # mkdir -p /usr/share/java/jboss-ec2-eap-applications
    # wget https://<your secure storage hostname>/<path>/<app name>.war -O /usr/share/java/jboss-ec2-eap-applications/<app name>.war
    
    ## Create a file of CLI commands to be executed after starting the server
    cat> $USER_CLI_COMMANDS << "EOC" 
    
    # Add the modcluster subsystem to the default profile to set up a proxy
    /profile=default/subsystem=web/connector=ajp:add(name=ajp,protocol=AJP/1.3,scheme=http,socket-binding=ajp)
    /:composite(steps=[ {"operation" => "add", "address" => [ ("profile" => "default"), ("subsystem" => "modcluster") ] },{ "operation" => "add", "address" => [ ("profile" => "default"), ("subsystem" => "modcluster"), ("mod-cluster-config" => "configuration") ], "advertise" => "false", "proxy-list" => "${jboss.modcluster.proxyList}", "connector" => "ajp"}, { "operation" => "add", "address" => [ ("profile" => "default"), ("subsystem" => "modcluster"), ("mod-cluster-config" => "configuration"), ("dynamic-load-provider" => "configuration") ]}, { "operation" => "add", "address" => [ ("profile" => "default"), ("subsystem" => "modcluster"), ("mod-cluster-config" => "configuration"), ("dynamic-load-provider" => "configuration"), ("load-metric" => "busyness")], "type" => "busyness"} ])
    
    # Deploy the sample application from the local filesystem
    deploy /usr/share/java/jboss-ec2-eap-samples/hello.war --server-groups=main-server-group
    EOC
    
    ## this will workaround the problem that in a VPC, instance hostnames are not resolvable
    echo -e "127.0.0.1\tlocalhost.localdomain localhost" > /etc/hosts
    echo -e "::1\tlocalhost6.localdomain6 localhost6" >> /etc/hosts
    for (( i=1 ; i<255 ; i++ )); do
       echo -e "$SUBNET$i\tip-${SUBNET//./-}$i" ;
    done >> /etc/hosts
    
    EOF
    
    
  5. 对于产品实例

    对于产品实例,在 User Data 字段的 USER_SCRIPT 行下面添加下列内容,确保在引导时进行安全更新。
    yum -y update

    注意

    yum -y update 应该经常运行以应用安全修复和增强。
  6. 启动 Red Hat AMI 实例。
结果

已在 Red Hat AMI 上配置并启动非群集的 JBoss EAP 6 受管域。

概况

本节涵盖了启动一个或多个 JBoss EAP 6 实例作为 Red Hat AMI(Amazon Machine Image)上的非群集主机控制器的步骤。

前提条件

过程 22.4. 启动主机控制器

对您要创建的每个实例,重复下列步骤:
  1. 选择 AMI
  2. 定义所需的实例数量(从主机控制器数量)。
  3. 选择 VPC 和实例类型。
  4. 点击『安全组』。
  5. 确保来自 JBoss EAP 6 子网的所有流量都是被允许的。
  6. 按需要定义其他限制。
  7. 在『User Data』字段添加下列内容:
    ## mod cluster proxy addresses
    MOD_CLUSTER_PROXY_LIST=10.0.0.4:7654
    
    ## host controller setup
    JBOSS_DOMAIN_MASTER_ADDRESS=10.0.0.5
    JBOSS_HOST_PASSWORD=<password for slave host controllers>
    
    ## subnet prefix this machine is connected to
    SUBNET=10.0.1.
    
    #### to run the example no modifications below should be needed ####
    JBOSS_HOST_USERNAME=admin
    PORTS_ALLOWED="1024:65535"
    JBOSS_IP=`hostname | sed -e 's/ip-//' -e 'y/-/./'` #listen on public/private EC2 IP address
    
    cat > $USER_SCRIPT << "EOF"
    ## Server instance configuration
    sed -i "s/other-server-group/main-server-group/" $JBOSS_CONFIG_DIR/$JBOSS_HOST_CONFIG
    
    ## this will workaround the problem that in a VPC, instance hostnames are not resolvable
    echo -e "127.0.0.1\tlocalhost.localdomain localhost" > /etc/hosts
    echo -e "::1\tlocalhost6.localdomain6 localhost6" >> /etc/hosts
    for (( i=1 ; i<255 ; i++ )); do
        echo -e "$SUBNET$i\tip-${SUBNET//./-}$i" ;
    done >> /etc/hosts
    
    EOF
    
  8. 对于产品实例

    对于产品实例,在 User Data 字段的 USER_SCRIPT 行下面添加下列内容,确保在引导时进行安全更新。
    yum -y update

    注意

    yum -y update 应该经常运行以应用安全修复和增强。
  9. 启动 Red Hat AMI 实例。
结果

已在 Red Hat AMI 上配置并启动了 JBoss EAP 6 非群集主机控制器。

22.2.2.3.3. 测试非群集 JBoss EAP 6 受管域
概况

本节涵盖在 Red Hat AMI(Amazon Machine Image)上测试非群集 JBoss EAP 6 受管域的步骤。

要测试受管域,您必须知道 Apache HTTPD 和 JBoss EAP 6 域控制器的弹性 IP 地址。

前提条件

过程 22.5. 测试 Web 服务器

  • 用浏览器访问 http://ELASTIC_IP_OF_APACHE_HTTPD 来确认 Web 服务器已成功运行。

过程 22.6. 测试域控制器

  1. 进入 http://ELASTIC_IP_OF_DOMAIN_CONTROLLER:9990/console
  2. 用用户名 admin 和 User Data 字段里为域控制器指定的密码登录。登录后,受管域的管理控制台登录页面将出现(http://ELASTIC_IP_OF_DOMAIN_CONTROLLER:9990/console/App.html#server-instances)。
  3. 点击屏幕右上角的 Server 标签,在屏幕左上角的 Host 下拉菜单里选择任何主机控制器。
  4. 检验每个主机控制器有两个服务器配置:server-oneserver-two,并检查它们都属于 main-server-group
  5. 登出 JBoss EAP 6 管理控制台。

过程 22.7. 测试主机控制器

  1. 访问 http://ELASTIC_IP_OF_APACHE_HTTPD/hello 来测试例程是否成功运行。Hello World! 文本应该出现在浏览器页面里。
    如果没看到这个文本,请参考:Section 18.5.1 - "About Troubleshooting Amazon EC2"。
  2. 连接 Apache HTTPD 实例:
    $ ssh -L7654:localhost:7654 ELASTIC_IP_OF_APACHE_HTTPD
  3. 访问 http://localhost:7654/mod_cluster-manager 以确认所有的实例都正常运行。
结果

Red Hat AMI 上的 JBoss EAP 6 Web 服务器、域控制器和主机控制器都正常运行。

22.2.3. 群集的 JBoss EAP 6

22.2.3.1. 关于群集实例
群集实例是运行 JBoss EAP 6 且启用了群集的 Amazon EC2 实例。运行 Apache HTTPD 的另外一个实例将充当群集里实例的代理。
JBoss EAP 6 AMI 包含两个用于群集实例的配置文件:standalone-ec2-ha.xmlstandalone-mod_cluster-ec2-ha.xml。每个配置文件都提供了群集功能而无需使用多点传送,这是因为 Amazon EC2 不支持多点传送。这是通过用于群集通讯的 TCP 单点传送和用于发现协议的 S3_PING 来实现的。standalone-mod_cluster-ec2-ha.xml 配置也提供 mod_cluster 代理的简单注册。
类似地,domain-ec2.xml 配置文件提供在群集受管域里使用的两个配置集:ec2-ha 和 mod_cluster-ec2-ha。
概况

本节介绍创建关系型数据库服务实例的步骤,以 MySQL 为例子。

警告

我们强烈推荐在产品环境里启用备份和维护功能。

重要

为访问数据库的每个应用程序都创建单独的用户/密码是不错的做法。请按照您的应用程序的需要调整其他配置选项。

过程 22.8. 创建一个关系型数据库服务的数据库实例

  1. 点击 AWS 控制台里的 RDS
  2. 如果需要则订阅这个服务。
  3. 点击 Launch DB instance
  4. 点击 MySQL
    1. 选择版本。例如:5.5.12
    2. 选择 small instance
    3. 确保 Multi-AZ DeploymentAuto upgradeoff
    4. 设置 Storage5GB
    5. 定义数据库管理员的用户名和密码并点击 Next
    6. 选择随实例一起创建的数据库的名称,并点击 Next
    7. 如果需要,禁用备份和维护。
    8. 确认设置。
结果

数据库已创建。数分钟后它将初始化并可以使用。

22.2.3.3. 关于虚拟私有云
Amazon 虚拟私有云(Virtual Private Cloud,VPC)是 Amazon Web Service(AWS)的一个功能,它允许您在私有网络里隔离一系列 AWS 资源。这个私有网络的拓扑和配置可以按照需要进行定制。
更多信息请参考 Amazon 虚拟私有云的网站:http://aws.amazon.com/vpc/
22.2.3.4. 创建虚拟私有云(VPC)
概况

本节以外部数据库为例,介绍创建虚拟私有云所需的步骤。您的安全策略可以要求到数据库的连接加密。关于加密数据库连接的详情,请参考 Amazon 的 RDS FAQ

重要

对于 JBoss EAP 6 群集设置,我们推荐使用 VPC。这是因为它极大地简化了群集节点、JON 服务器及 mod_cluster 代理间的安全连接。如不使用 VPC,这些通讯频道都需要加密和验证。
关于配置 SSL 的详细说明,请参考:第 10.12.1 节 “对 JBoss EAP 6 Web 服务器实施 SSL 加密”
  1. 点击 AWS 控制台里的 VPC 标签页。
  2. 如果需要则订阅这个服务。
  3. 点击 "Create new VPC"。
  4. 选择带有一个公共子网和一个私有子网的 VPC。
    1. 设置公共子网为 10.0.0.0/24
    2. 设置私有子网为 10.0.1.0/24
  5. 进入 Elastic IPs
  6. 创建一个 mod_cluster proxy/NAT 实例使用的弹性 IP 地址。
  7. 进入 Security groups 并创建一个安全组来允许所有流量的进出。
  8. 进入 Network ACLs。
    1. 创建 ACL 来允许所有流量进出。
    2. 创建 ACL 来允许所有流量只通过 TCP 端口 228009808084439443999016163 进出。
结果

成功地创建了虚拟私有云(VPC)。

概况

本节介绍启动 Apache HTTPD 实例作为 VPC 的 mod_cluster 代理和 NAT 实例所需的步骤。

过程 22.9. 启动 Apache HTTPD 实例作为 VPC 的 mod_cluster 代理和 NAT 实例

  1. 为这个实例创建一个有弹性的 IP 地址。
  2. 选择 AMI
  3. 进入 Security Group 并允许所有流量(如果需要的话用 Red Hat 企业版 Linux 的内置防火墙功能来限制访问)。
  4. 在 VPC 的公共子网里选择 "running"。
  5. 选择一个静态 IP (如:10.0.0.4)。
  6. User Data: 字段添加下列内容:
    JBOSSCONF=disabled
    
    cat > $USER_SCRIPT << "EOS"
    
    echo 1 > /proc/sys/net/ipv4/ip_forward
    echo 0 > /proc/sys/net/ipv4/conf/all/rp_filter
    echo 0 > /proc/sys/net/ipv4/conf/eth0/rp_filter
    
    iptables -I INPUT 4 -s 10.0.1.0/24 -p tcp --dport 7654 -j ACCEPT
    iptables -I INPUT 4 -p tcp --dport 80 -j ACCEPT
    
    iptables -I FORWARD -m state --state RELATED,ESTABLISHED -j ACCEPT
    iptables -I FORWARD -s 10.0.1.0/24 -j ACCEPT
    iptables -t nat -A POSTROUTING -o eth0 ! -s 10.0.0.4 -j MASQUERADE
    
    # balancer module incompatible with mod_cluster
    sed -i -e 's/LoadModule proxy_balancer_module/#\0/' /etc/httpd/conf/httpd.conf
    
    cat > /etc/httpd/conf.d/mod_cluster.conf << "EOF"
    #LoadModule proxy_module modules/mod_proxy.so
    #LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
    LoadModule slotmem_module modules/mod_slotmem.so
    LoadModule manager_module modules/mod_manager.so
    LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
    LoadModule advertise_module modules/mod_advertise.so
    
    Listen 7654
    
    # workaround JBPAPP-4557
    MemManagerFile /var/cache/mod_proxy/manager
    
    <VirtualHost *:7654>
       <Location /mod_cluster-manager>
          SetHandler mod_cluster-manager
          Order deny,allow
          Deny from all
          Allow from 127.0.0.1
       </Location>
    
       <Location />
          Order deny,allow
          Deny from all
          Allow from 10.
          Allow from 127.0.0.1
       </Location>
    
       KeepAliveTimeout 60
       MaxKeepAliveRequests 0
       ManagerBalancerName mycluster
       ServerAdvertise Off
       EnableMCPMReceive On
    </VirtualHost>
    EOF
    
    echo "`hostname | sed -e 's/ip-//' -e 'y/-/./'`        `hostname`" >> /etc/hosts
    
    semanage port -a -t http_port_t -p tcp 7654 #add port in the apache port list for the below to work
    setsebool -P httpd_can_network_relay 1 #for mod_proxy_cluster to work
    chcon -t httpd_config_t -u system_u /etc/httpd/conf.d/mod_cluster.conf
    
    #### Uncomment the following line when launching a managed domain ####
    # setsebool -P httpd_can_network_connect 1
    
    service httpd start
    
    EOS
    
    
  7. 禁用这个实例的 Amazon EC2 云源/目的地检查,让它可以充当路由器。
    1. 右击运行的 Apache HTTPD 实例并选择 "Change Source/Dest check"。
    2. 点击 Yes, Disable
  8. 为这个实例分配弹性 IP 地址。
结果

已成功启动 Apache HTTPD 实例。

22.2.3.6. 配置 VPC 私有子网的默认路由
概况

本节涵盖配置 VPC 私有子网默认路由所需的步骤。JBoss EAP 6 群集节点将运行在 VPC 的私有子网里,但群集节点要求访问互联网以实现 S3 连接性。您需要设置默认路由可以通过 NAT 实例。

过程 22.10. 配置 VPC 私有子网的默认路由

  1. 在 Amazon AWS 控制台里进入 Apache HTTPD 实例。
  2. 选择 VPC route tables
  3. 点击私有子网使用的路由表。
  4. 在新路由字段里输入 0.0.0.0/0
  5. 点击 "Select a target"。
  6. 选择 "Enter Instance ID"。
  7. 选择运行的 Apache HTTPD 实例的 ID。
结果

已成功为 VPC 子网配置了默认路由。

标识符和访问管理为 AWS 资源提供了可配置的安全性。您可以配置 IAM 使用在 IAM 里创建的帐号或提供 IAM 和自己的标识符服务间的标识符联合机制。
更多信息请参考 AWS 标识符和访问管理网站:http://aws.amazon.com/iam/
22.2.3.8. 配置 IAM 设置
概述总结

本节涵盖为群集 JBoss EAP 6 实例设立 IAM 所需的配置步骤。S3_PING 协议使用 S3 Bucket 来发现其他群集成员。JGroups 3.0.x 版本要求 Amazon AWS 帐号及安全密钥来对 S3 服务进行验证。

在 user-data 字段输入主帐号凭证是有安全风险的,请将其在线存储或放在 AMI 里。要避免这种风险,您可以用 Amazon IAM 功能来创建单独的帐号,它只被赋予对单个 S3 Bucket 的访问权限。

过程 22.11. 配置 IAM 设置

  1. 点击 AWS 控制台里的 IAM 标签页。
  2. 点击 users
  3. 选择 Create New Users
  4. 选择名称并确保选择 Generate an access key for each User 选项。
  5. 选择 Download credentials 并将其保存在安全的位置。
  6. 关闭窗口。
  7. 点击新创建的用户。
  8. 记下 User ARM 的值。设置 S3 Bucket 要求这个值,其文档位于 第 22.2.3.10 节 “配置 S3 Bucket”
结果

成功地创建了 IAM 用户帐号。

22.2.3.9. 关于 S3 Bucket
S3 Bucket 是 Amazon 简单存储系统(Amazon S3)里地基本机构存储单元。Bucket 可以存储任意数目的对象且在 Amazon S3 里必须具有唯一的名称进行标识。
更多信息请参考 Amazon S3 网站 http://aws.amazon.com/s3/
22.2.3.10. 配置 S3 Bucket
概况

这个主题涵盖了配置新 S3 Bucket 所需的步骤。

过程 22.12. 配置 S3 Bucket

  1. 在 AWS 控制台里打开 S3 标签页。
  2. 点击 Create Bucket
  3. 为这个 Bucket 选择一个名称并点击 Create

    注意

    Bucket 名称在整个 S3 里是唯一的。它的名称不能被重用。
  4. 右击新的 Bucket 并选择 Properties
  5. 点击 permissions 标签页里的 Add bucket policy
  6. 点击 New policy 来打开策略创建向导。
    1. 复制下列内容到新的策略里,用这里定义的值替换 arn:aws:iam::05555555555:user/jbosscluster*第 22.2.3.8 节 “配置 IAM 设置”。修改 clusterbucket123 的两个实例为这个过程里步骤 3 中定义的 Bucket 的名称。
      {
          "Version": "2008-10-17",
          "Id": "Policy1312228794320",
          "Statement": [
              {
                  "Sid": "Stmt1312228781799",
                  "Effect": "Allow",
                  "Principal": {
                      "AWS": [
                          "arn:aws:iam::055555555555:user/jbosscluster"
                      ]
                  },
                  "Action": [
                      "s3:ListBucketVersions",
                      "s3:GetObjectVersion",
                      "s3:ListBucket",
                      "s3:PutBucketVersioning",
                      "s3:DeleteObject",
                      "s3:DeleteObjectVersion",
                      "s3:GetObject",
                      "s3:ListBucketMultipartUploads",
                      "s3:ListMultipartUploadParts",
                      "s3:PutObject",
                      "s3:GetBucketVersioning"
                  ],
                  "Resource": [
                      "arn:aws:s3:::clusterbucket123/*",
                      "arn:aws:s3:::clusterbucket123"
                  ]
              }
          ]
      }
      
      
结果

新的 S3 Bucket 已被成功创建和配置。

22.2.3.11. 群集实例
22.2.3.11.1. 启动群集 JBoss EAP 6 AMI
总结

本节涵盖启动群集 JBoss EAP 6 AMI 的步骤

警告

在带有小于 24 位掩码的子网里或跨越多个子网运行 JBoss EAP 6 群集要求每个群集成员都对应唯一的服务器对等 ID。
关于如何使这样的配置可靠地运行,请参考 JBOSS_CLUSTER_ID 变量。

重要

Amazon EC2 的 auto-scaling 功能可能用于 JBoss EAP 6 群集节点。然而,请确保在部署进行测试。您应该确保特定的工作负荷分摊到多个节点上,且性能满足对计划使用的实例的需要(不同实例类型接收不同比例的 EC2 云资源)。
而且,实例位置和当前网络/存储/主机/RDS 利用率都可能影响群集的性能。请用期望的实际负荷进行测试并预计意外的条件。

警告

Amazon EC2 scale-down 动作终止节点而不会优雅地关闭节点,某些事务可能会被中断,其他群集节点(和负载平衡)将需要时间来进行失效切换。这很可能影响到应用程序的用户体验。
我们推荐您在 mod_cluster 管理接口里禁用服务器直至会话完成来缩减应用程序群集规模,或者是优雅地关闭 JBoss EAP 6 实例(可以用 SSH 访问实例或使用 JON)。
测试您缩减的过程是否导致对用户体验起反作用。对于特定的工作负荷、负载平衡和设立可能需要其他的措施。

过程 22.13. 启动群集 JBoss EAP 6 AMI

  1. 选择 AMI
  2. 定义想要的实例的数量(群集大小)。
  3. 选择 VPC 和实例类型。
  4. 点击 Security Group
  5. 确保 JBoss EAP 6 群集子网的所有流量都是被允许的。
  6. 按需要定义其他限制。
  7. User Data 字段里添加下列内容:

    例 22.5. 『User Data』字段示例

    ## mod cluster proxy addresses
    MOD_CLUSTER_PROXY_LIST=10.0.0.4:7654
    
    ## clustering setup
    JBOSS_JGROUPS_S3_PING_SECRET_ACCESS_KEY=<your secret key>
    JBOSS_JGROUPS_S3_PING_ACCESS_KEY=<your access key>
    JBOSS_JGROUPS_S3_PING_BUCKET=<your bucket name>
    
    ## password to access admin console
    JBOSSAS_ADMIN_PASSWORD=<your password for opening admin console>
    
    ## database credentials configuration
    JAVA_OPTS="$JAVA_OPTS -Ddb.host=instancename.something.rds.amazonaws.com -Ddb.database=mydatabase -Ddb.user=<user> -Ddb.passwd=<pass>"
    
    ## subnet prefix this machine is connected to
    SUBNET=10.0.1.
    
    #### to run the example no modifications below should be needed ####
    PORTS_ALLOWED="1024:65535"
    JBOSS_IP=`hostname | sed -e 's/ip-//' -e 'y/-/./'` #listen on public/private EC2 IP address
    
    cat > $USER_SCRIPT << "EOF"
    ## Get the application to be deployed from an Internet URL
    # mkdir -p /usr/share/java/jboss-ec2-eap-applications
    # wget https://<your secure storage hostname>/<path>/<app name>.war -O /usr/share/java/jboss-ec2-eap-applications/<app name>.war
    
    ## install the JDBC driver as a core module
    yum -y install mysql-connector-java
    mkdir -p /usr/share/jbossas/modules/com/mysql/main
    cp -v /usr/share/java/mysql-connector-java-*.jar /usr/share/jbossas/modules/com/mysql/main/mysql-connector-java.jar
    
    cat > /usr/share/jbossas/modules/com/mysql/main/module.xml <<"EOM"
    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="com.mysql">
       <resources>
          <resource-root path="mysql-connector-java.jar"/>
       </resources>
       <dependencies>
          <module name="javax.api"/>
       </dependencies>
    </module>
    EOM
    
    cat > $USER_CLI_COMMANDS << "EOC" 
    ## Deploy sample application from local filesystem
    deploy --force /usr/share/java/jboss-ec2-eap-samples/cluster-demo.war
    
    ## ExampleDS configuration for MySQL database
    data-source remove --name=ExampleDS
    /subsystem=datasources/jdbc-driver=mysql:add(driver-name="mysql",driver-module-name="com.mysql")
    data-source add --name=ExampleDS --connection-url="jdbc:mysql://${db.host}:3306/${db.database}" --jndi-name=java:jboss/datasources/ExampleDS --driver-name=mysql --user-name="${db.user}" --password="${db.passwd}"
    /subsystem=datasources/data-source=ExampleDS:enable
    /subsystem=datasources/data-source=ExampleDS:test-connection-in-pool
    EOC
    
    ## this will workaround the problem that in a VPC, instance hostnames are not resolvable
    echo -e "127.0.0.1\tlocalhost.localdomain localhost" > /etc/hosts
    echo -e "::1\tlocalhost6.localdomain6 localhost6" >> /etc/hosts
    for (( i=1 ; i<255 ; i++ )); do
       echo -e "$SUBNET$i\tip-${SUBNET//./-}$i" ;
    done >> /etc/hosts
    
    EOF
    
结果

已成功配置和启动群集 JBoss EAP 6 AMI。

22.2.3.11.2. 测试群集 JBoss EAP 6 实例
总结

本节涵盖了确认群集 JBoss EAP 6 实例正确运行的步骤。

过程 22.14. 测试群集实例

  1. 用浏览器访问 http://ELASTIC_IP_OF_APACHE_HTTPD 来确认 Web 服务器已成功运行。
  2. 测试群集节点

    1. 检验某个群集节点是否记录如下的消息:
      Putting date now
    2. 停止在之前步骤里记录消息的节点。
    3. 检验显示的时间和步骤 2-a 里用 put.jsp PUT 的时间相同。
    4. 检验某个运行的群集节点是否记录如下的消息:
      Getting date now
    5. 重启已停止的群集节点。
    6. 连接 Apache HTTPD 实例:
      ssh -L7654:localhost:7654 <ELASTIC_IP_OF_APACHE_HTTPD>
    7. 访问 http://localhost:7654/mod_cluster-manager 以确认所有的实例都正常运行。
结果

已测试群集的JBoss EAP 6 实例且确认都工作正常。

22.2.3.12. 群集的受管域
22.2.3.12.1. 启动一个实例作为群集域控制器
总结

本节涵盖在 Red Hat AMI(Amazon Machine Image)上启动群集 JBoss EAP 6 受管域的步骤。

过程 22.15. 启动群集域控制器

  1. 为这个实例创建一个有弹性的 IP 地址。
  2. 选择 AMI。
  3. 进入 Security Group 并允许所有流量(如果需要的话用 Red Hat 企业版 Linux 的内置防火墙功能来限制访问)。
  4. 在 VPC 的公共子网里选择 "running"。
  5. 选择一个静态 IP (如:10.0.0.5)。
  6. 在『User Data』字段添加下列内容:
    ## mod cluster proxy addresses
    MOD_CLUSTER_PROXY_LIST=10.0.0.4:7654
     
    ## password that will be used by slave host controllers to connect to the domain controller
    JBOSSAS_ADMIN_PASSWORD=<password for slave host controllers>
     
    ## subnet prefix this machine is connected to
    SUBNET=10.0.0.
     
    #### to run the example no modifications below should be needed ####
    JBOSS_DOMAIN_CONTROLLER=true
    PORTS_ALLOWED="9999 9990 9443"
    JBOSS_IP=`hostname | sed -e 's/ip-//' -e 'y/-/./'` #listen on public/private EC2 IP address
     
    cat > $USER_SCRIPT << "EOF"
    ## Get the application to be deployed from an Internet URL
    # mkdir -p /usr/share/java/jboss-ec2-eap-applications
    # wget https://<your secure storage hostname>/<path>/<app name>.war -O /usr/share/java/jboss-ec2-eap-applications/<app name>.war
     
    ## Install the JDBC driver as a core module
    yum -y install mysql-connector-java
    mkdir -p /usr/share/jbossas/modules/com/mysql/main
    cp -v /usr/share/java/mysql-connector-java-*.jar /usr/share/jbossas/modules/com/mysql/main/mysql-connector-java.jar
     
    cat > /usr/share/jbossas/modules/com/mysql/main/module.xml <<"EOM"
    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="com.mysql">
       <resources>
          <resource-root path="mysql-connector-java.jar"/>
       </resources>
       <dependencies>
          <module name="javax.api"/>
       </dependencies>
    </module>
    EOM
     
    cat > $USER_CLI_COMMANDS << "EOC" 
    ## Deploy the sample application from the local filesystem
    deploy /usr/share/java/jboss-ec2-eap-samples/cluster-demo.war --server-groups=other-server-group
     
    ## ExampleDS configuration for MySQL database
    data-source --profile=mod_cluster-ec2-ha remove --name=ExampleDS
    /profile=mod_cluster-ec2-ha/subsystem=datasources/jdbc-driver=mysql:add(driver-name="mysql",driver-module-name="com.mysql")
    data-source --profile=mod_cluster-ec2-ha add --name=ExampleDS --connection-url="jdbc:mysql://${db.host}:3306/${db.database}" --jndi-name=java:jboss/datasources/ExampleDS --driver-name=mysql --user-name="${db.user}" --password="${db.passwd}"
    /profile=mod_cluster-ec2-ha/subsystem=datasources/data-source=ExampleDS:enable
    EOC
     
    ## this will workaround the problem that in a VPC, instance hostnames are not resolvable
    echo -e "127.0.0.1\tlocalhost.localdomain localhost" > /etc/hosts
    echo -e "::1\tlocalhost6.localdomain6 localhost6" >> /etc/hosts
    for (( i=1 ; i<255 ; i++ )); do
       echo -e "$SUBNET$i\tip-${SUBNET//./-}$i" ;
    done >> /etc/hosts
     
    EOF
    
  7. 对于产品实例

    对于产品实例,在 User Data 字段的 USER_SCRIPT 行下面添加下列内容,确保在引导时进行安全更新。
    yum -y update

    注意

    yum -y update 应该经常运行以应用安全修复和增强。
  8. 启动 Red Hat AMI 实例。
结果

已在 Red Hat AMI 上配置并启动群集的 JBoss EAP 6 受管域。

概述

本节涵盖了启动一个或多个 JBoss EAP 6 实例作为 Red Hat AMI(Amazon Machine Image)上的群集主机控制器的步骤。

前提条件

过程 22.16. 启动主机控制器

对您要创建的每个实例,重复下列步骤:
  1. 选择 AMI
  2. 定义所需的实例数量(从主机控制器数量)。
  3. 选择 VPC 和实例类型。
  4. 点击『安全组』。
  5. 确保来自 JBoss EAP 6 群集子网的所有流量都是被允许的。
  6. 按需要定义其他限制。
  7. 在『User Data』字段添加下列内容:
    ## mod cluster proxy addresses
    MOD_CLUSTER_PROXY_LIST=10.0.0.4:7654
     
    ## clustering setup
    JBOSS_JGROUPS_S3_PING_SECRET_ACCESS_KEY=<your secret key>
    JBOSS_JGROUPS_S3_PING_ACCESS_KEY=<your access key>
    JBOSS_JGROUPS_S3_PING_BUCKET=<your bucket name>
     
    ## host controller setup
    JBOSS_DOMAIN_MASTER_ADDRESS=10.0.0.5
    JBOSS_HOST_PASSWORD=<password for slave host controllers>
     
    ## database credentials configuration
    JAVA_OPTS="$JAVA_OPTS -Ddb.host=instancename.something.rds.amazonaws.com -Ddb.database=mydatabase -Ddb.user=<user> -Ddb.passwd=<pass>"
     
    ## subnet prefix this machine is connected to
    SUBNET=10.0.1.
     
    #### to run the example no modifications below should be needed ####
    JBOSS_HOST_USERNAME=admin
    PORTS_ALLOWED="1024:65535"
    JBOSS_IP=`hostname | sed -e 's/ip-//' -e 'y/-/./'` #listen on public/private EC2 IP address
     
    cat > $USER_SCRIPT << "EOF"
    ## Server instance configuration
    sed -i "s/main-server-group/other-server-group/" $JBOSS_CONFIG_DIR/$JBOSS_HOST_CONFIG
     
    ## install the JDBC driver as a core module
    yum -y install mysql-connector-java
    mkdir -p /usr/share/jbossas/modules/com/mysql/main
    cp -v /usr/share/java/mysql-connector-java-*.jar /usr/share/jbossas/modules/com/mysql/main/mysql-connector-java.jar
     
    cat > /usr/share/jbossas/modules/com/mysql/main/module.xml <<"EOM"
    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="com.mysql">
       <resources>
          <resource-root path="mysql-connector-java.jar"/>
       </resources>
       <dependencies>
          <module name="javax.api"/>
       </dependencies>
    </module>
    EOM
     
    ## this will workaround the problem that in a VPC, instance hostnames are not resolvable
    echo -e "127.0.0.1\tlocalhost.localdomain localhost" > /etc/hosts
    echo -e "::1\tlocalhost6.localdomain6 localhost6" >> /etc/hosts
    for (( i=1 ; i<255 ; i++ )); do
       echo -e "$SUBNET$i\tip-${SUBNET//./-}$i" ;
    done >> /etc/hosts
     
    EOF
    
  8. 对于产品实例

    对于产品实例,在 User Data 字段的 USER_SCRIPT 行下面添加下列内容,确保在引导时进行安全更新。
    yum -y update

    注意

    yum -y update 应该经常运行以应用安全修复和增强。
  9. 启动 Red Hat AMI 实例。
结果

已在 Red Hat AMI 上配置并启动了 JBoss EAP 6 群集主机控制器。

22.2.3.12.3. 测试群集 JBoss EAP 6 受管域
总结

本节涵盖在 Red Hat AMI(Amazon Machine Image)上测试群集 JBoss EAP 6 受管域的步骤。

要测试受管域,您必须知道 Apache HTTPD 和 JBoss EAP 6 域控制器的弹性 IP 地址。

前提条件

过程 22.17. 测试 Apache HTTPD 实例

  • 用浏览器访问 http://ELASTIC_IP_OF_APACHE_HTTPD 来确认 Web 服务器已成功运行。

过程 22.18. 测试域控制器

  1. 进入 http://ELASTIC_IP_OF_DOMAIN_CONTROLLER:9990/console
  2. 用用户名 admin 和 User Data 字段里为域控制器指定的密码登录。登录后,受管域的管理控制台登录页面将出现(http://ELASTIC_IP_OF_DOMAIN_CONTROLLER:9990/console/App.html#server-instances)。
  3. 点击屏幕右上角的 Server 标签。在屏幕左上角的 Host 下拉菜单里选择任何主机控制器。
  4. 检验这个主机控制器有两个服务器配置:server-oneserver-two,并检查它们都属于 other-server-group

过程 22.19. 测试主机控制器

  1. 用浏览器访问 http://ELASTIC_IP_OF_APACHE_HTTPD/cluster-demo/put.jsp
  2. 检验其中一个主机控制器记录下列日志:Putting date now.
  3. 停止在之前步骤里记录消息的服务器实例(请参考 2.8.3 章节 - Stop a Server Using the Management Console)。
  4. 用浏览器访问 http://ELASTIC_IP_OF_APACHE_HTTPD/cluster-demo/get.jsp
  5. 检验显示的时间和步骤 2-a 里用 put.jsp PUT 的时间相同。
  6. 检验其中一个服务器实例记录下列日志:Getting date now.
  7. 重启已停止的服务器实例(请参考 2.8.3 章节 - Start a Server Using the Management Console)
  8. 连接至 Apache HTTPD 实例。
    $ ssh -L7654:localhost:7654 ELASTIC_IP_OF_APACHE_HTTPD
  9. 访问 http://localhost:7654/mod_cluster-manager 以确认所有的实例都正常运行。
结果

Red Hat AMI 上的 JBoss EAP 6 Web 服务器、域控制器和主机控制器都正常运行。

22.3. 用 JBoss Operations Network (JON) 建立监控

22.3.1. 关于 AMI 监控

将商业应用程序部署到正确配置的 AMI 实例后,下一步是用 JBoss Operations Network (JON) 建立平台的监控。
JON 服务器通常位于机构网络内部,所以有必要在服务器和代理间建立一个安全的连接。最常见的方案是在两点间建立 VPN,但这会使所需的网络配置变得复杂。本章提供了在 JON 代理和 JON 服务器间启用通讯的网络配置准则。关于配置、管理和使用的更多信息,请参考 JBoss Operations Network (JON) 官方文档。
JON 服务器连接性

图 22.1. JON 服务器连接性

22.3.2. 关于连接性的要求

在服务器里注册 JON 代理要求代理和服务器间的双路通讯。JON 代理需要访问所有 JON 服务器上的端口 7080,使用 SSL 时则是端口 7443。每个 JON 服务器必须能够访问具有唯一主机和端口的每个连接的代理。代理端口通常是 16163。
如果有多个群集 JON 服务器,请确保每个代理可以通过在 JON 服务器管理控制台里配置的 IP 地址和主机名对与 JON 群集里的所有服务器进行通讯。代理注册时使用的 JON 服务器和它在初始化后试图使用的服务器可能不同。
路由模式的机构 VPN 网关极大地简化了网络配置。如果您的机构 VPN 网关使用 NAT 模式,JON 服务器则无法直接看到代理。此时,您必须为每个代理配置端口转发。
NAT VPN 配置要求转发网关上一个端口到受管域上 JON 代理的端口地址。您也需要配置 JON 代理以告知服务器转发端口号和 IP 地址。您可以在 agent-configuration.xml 配置文件的 rhq.communications.connector.* 描述里找到更多信息。

22.3.4. 关于 Amazon EC2 和 DNS

JON 服务器和 JON 代理需要解析彼此的主机名。DNS 解析在 VPN 配置里更为复杂。连接的服务器有多个可能的选项。一个选项是使用 Amazon EC2 或机构网络的 DNS 服务器。另外一个选项是使用独立的 DNS 配置,机构 DNS 服务器用来解析特定域里的名称,而 Amazon EC2 DNS 服务器则用来解析所有其他的名称。

22.3.5. 关于 EC2 里的路由

所有的 Amazon EC2 服务器默认都激活了一个 source/destination checking 路由功能。这个功能将发送到服务器的目的地和主机的 IP 地址不一致的数据包丢弃。如果连接代理到 JON 服务器的 VPN 方案包括了一个路由器,您需要关闭这个功能,或者将服务器作为路由器或 VPN 网关。这个配置设置可以通过 Amazon AWS 控制台进行访问。虚拟私有云(Virtual Private Cloud,VPC)里也要求禁用 source/destination checking
某些 VPN 配置默认将普通的流量通过机构 VPN 进行路由。我们推荐您避免这样做,因为这可能是较慢和低效的配置方式。
虽然使用正确的地址模式并不是 JON 专有的需要担心的事情,但较差的模式可能会有不良影响。Amazon EC2 从 10.0.0.0/8 开始分配 IP 地址。实例通常也具有一个公用 IP 地址,但只有相同可用性区内部 IP 地址上的网络流量才是自由的。要避免在私有网络里使用 10.0.0.0/8 段的地址,您需要考虑几件事情。
  • 在创建 VPC 时,不要分配已经用在私有网络里的地址以避免连接性问题。
  • 如果某个实例需要访问可用性区的本地资源,请确保使用 Amazon EC2 私有地址且流量不通过 VPN 来路由。
  • 如果 Amazon EC2 实例将访问机构私有网络地址的一个小的子集(如只有 JON 服务器),只有这些地址应该通过 VPN 进行路由。这增强了安全性并降低了 Amazon EC2 或私有网络地址空间冲突的机会。

22.3.6. 关于终止和重启 JON

云环境的其中一个益处是您可以轻易终止和启动主机实例。您也可以启动和初始实例等同的实例。如果新实例试图用和之前运行的代理相同的名称来注册 JON 服务器,那可能会出现问题。如果是这样,JON 服务器不会再允许代理用缺失或不匹配的标识符令牌来进行重新连接。
要避免这样,请确保在试图用相同的名称连接代理之前从 JON 库存删除被终止的代理,或者在启动新代理时指定正确的标识符令牌。
当代理被分配了不再匹配 JON 配置里记录的新的 VPN IP 地址时,您可能遇到另一个问题。例如主机被重启或 VPN 连接给终止时。在这种情况下,我们推荐您将 JON 代理的生命周期和 VPN 连接的生命周期绑定。如果连接掉线,您可以停止代理。当连接恢复时,请更新 /etc/sysconfig/jon-agent-ec2 里的 JON_AGENT_ADDR 来反映新的 IP 地址并重启代理。
关于如何修改代理的 IP 地址,请参考 https://access.redhat.com/site/documentation/JBoss_Operations_Network/ 上的《配置 JON 服务器和代理指南》。
如果需要启动和/或终止大量的实例,手动从 JON 库存里添加和删除就不太现实了。JON 的脚本功能可以用来自动化这些步骤。进一步的信息请参考 JON 文档。

22.3.7. 配置实例来注册 JBoss Operations Network

使用下列过程来注册 JBoss EAP 6 实例到 JBoss Operations Network。
  • 对于 JBoss EAP 6,在 User Data 字段里添加下列内容。
    JON_SERVER_ADDR=jon2.it.example.com
    ## if instance not already configured to resolve its hostname
    JON_AGENT_ADDR=`ip addr show dev eth0 primary to 0/0 | sed -n 's#.*inet \([0-9.]\+\)/.*#\1#p'` 
    PORTS_ALLOWED=16163
    # insert other JON options when necessary, see Appendix I
    
    

22.4. 用户脚本配置

22.4.1. 永久性的配置参数

概述

下面的参数可用来影响 JBoss EAP 6 的配置和操作。它们的内容会写入到 /etc/sysconfig/jbossas/etc/sysconfig/jon-agent-ec2 里。

Expand
表 22.2. 可配置参数
名称 描述 默认值
JBOSS_JGROUPS_S3_PING_ACCESS_KEY 如果使用群集,用于 S3_PING 发现的 Amazon AWS 用户帐号的访问密钥。 N/A
JBOSS_JGROUPS_S3_PING_SECRET_ACCESS_KEY Amazon AWS 用户帐号的秘密访问密钥。 N/A
JBOSS_JGROUPS_S3_PING_BUCKET 用于 S3_PING 发现的 Amazon S3 bucket。 N/A
JBOSS_CLUSTER_ID
群集成员节点的 ID。只用于群集。接受的值为(按顺序):
  • 0 - 1023 范围内的有效群集 DI 号码。
  • 网络接口名称,其值使用 IP 地址的最后八位。
  • “S3” 将通过 JGroup 的 S3_PING 使用的 S3 Bucket 协调 ID 的使用。
    当所有群集节点都位于相同的 24 或更多位子网(例如,位于 VPC 子网)里时,我们推荐使用 IP 的最后八位(默认)。
eth0 地 IP 地址的最后八位
MOD_CLUSTER_PROXY_LIST 如果使用 mod_cluster,用逗号隔开的 mod_cluster 代理的 IP/主机名的列表。 N/A
PORTS_ALLOWED 除了默认的端口,防火墙允许的转入端口列表。 N/A
JBOSSAS_ADMIN_PASSWORD admin 用户的密码。 N/A
JON_SERVER_ADDR 要注册的 JON 服务器主机名或 IP。这仅用于注册,之后代理可能会与 JON 群集里其他服务器进行通讯。 N/A
JON_SERVER_PORT 代理与服务器通讯时使用的端口。 7080
JON_AGENT_NAME JON 代理的名称,必须是唯一的。 实例的 ID。
JON_AGENT_PORT 代理侦听的端口。 16163
JON_AGENT_ADDR JON 代理要绑定的 IP 地址。当服务器有多个公共地址(如 VPN)时使用它。 JON 代理默认会选择本地主机的 IP 地址。
JON_AGENT_OPTS 可用来配置 SSL、NAT 和其他高级设置的 JON 代理系统属性。 N/A
JBOSS_SERVER_CONFIG
要使用的 JBoss EAP 服务器配置文件名称。如果 JBOSS_DOMAIN_CONTROLLER=true,那么 domain-ec2.xml 将被使用。否则:
  • 如果 S3 config 已存在,则使用 standalone-ec2-ha.xml
  • 如果指定了 MOD_CLUSTER_PROXY_LIST,那么将选择 standalone-mod_cluster-ec2-ha.xml
  • 如果没有使用这两个选项,那将使用 standalone.xml 文件。
  • 也可以设置为 standalone-full.xml
standalone.xmlstandalone-full.xmlstandalone-ec2-ha.xmlstandalone-mod_cluser-ec2-ha.xmldomain-ec2.xml,取决于其他参数。
JAVA_OPTS JBoss EAP 6 启动前添加到命令参数里的自定义值。 JAVA_OPTS 是有其他参数的值组成的。
JBOSS_IP 服务器要绑定的 IP 地址。 127.0.0.1
JBOSSCONF 启动的 JBoss EAP 6 配置集的名称。要阻止 JBoss EAP 6 启动,JBOSSCONF 应设置为 disabled standalone
JBOSS_DOMAIN_CONTROLLER
设置这个实例是否将以域控制器运行。
false
JBOSS_DOMAIN_MASTER_ADDRESS
远程域控制器的 IP 地址。
N/A
JBOSS_HOST_NAME
逻辑主机名(域内)。这必须是可区分的名称。
HOSTNAME 环境变量的值。
JBOSS_HOST_USERNAME
当在域控制器里注册时主机控制器应使用的用户名。如果没有指定,将使用 JBOSS_HOST_NAME。
JBOSS_HOST_NAME
JBOSS_HOST_PASSWORD
当在域控制器里注册时主机控制器应使用的密码。
N/A
JBOSS_HOST_CONFIG
如果 JBOSS_DOMAIN_CONTROLLER=true,那么 host-master.xml 将被使用。如果 JBOSS_DOMAIN_MASTER_ADDRESS 已存在,那么 host-slave.xml 将被使用。
host-master.xmlhost-slave.xml,取决于其他参数。

22.4.2. 自定义脚本参数

概况

User Data: 字段的用户定制部分可使用下面的参数 。

Expand
表 22.3. 可配置参数
名称 描述
JBOSS_DEPLOY_DIR
活动的配置集的部署目录(例如,/var/lib/jbossas/standalone/deployments/)。放在这个目录里的可部署归档将被部署。Red Hat 推荐使用管理控制台或 CLI 工具而不是编辑配置文件来管理部署。
JBOSS_CONFIG_DIR
活动配置集的配置目录(例如:/var/lib/jbossas/standalone/configuration)。
JBOSS_HOST_CONFIG
活动的主机配置文件的名称(例如,host-master.xml)。Red Hat 推荐使用管理控制台或 CLI 工具而不是编辑配置文件来配置服务器。
JBOSS_SERVER_CONFIG
活动的服务器配置文件的名称(例如,standalone-ec2-ha.xml)。Red Hat 推荐使用管理控制台或 CLI 工具而不是编辑配置文件来配置服务器。
USER_SCRIPT
自定义配置脚本的路径,在获取 user-data 配置前可用。
USER_CLI_COMMANDS
CLI 命令的自定义文件的路径,在获取 user-data 配置前可用。

22.5. 故障排除

22.5.1. 关于 Amazon EC2 的故障解除

EC2 为每个实例提供了一个警告状态(Alarm Status),表示严重的故障。但缺乏这个警告并不保证实例已正确启动且服务运行正常。您可以使用 Amazon CloudWatch 及其自定义的度量功能来监控实例状态,但我们推荐使用企业级管理方案。JON 可以自动发现、监控和管理安装了 JON 代理的 EC2 实例上的许多服务,包括 JBoss EAP 6 及其服务:Tomcat、Httpd、PostgreSQL 等。既然 EC 上的和本地的 JBoss EAP 6 实例没有区别,两种类型的部署的 JON 监控应该是一样的。

22.5.2. 诊断信息

在 JON、Amazon CloudWatch 或手动检测到问题时,诊断信息的常见来源是:
  • /var/log/jboss_user-data.out 是 jboss-ec2-eap init 和用户自定义配置脚本的输出。
  • /var/cache/jboss-ec2-eap/ 包含实际的用户数据、启动实例使用的自定义脚本和自定义 CLI 命令。
  • /var/log 也包含从主机启动、JBoss EAP 6、httpd 和其他大多数服务采集的日志。
访问这些文件只能通过 SSH 会话。关于如何配置和建立与 Amazon EC2 实例间的 SSH 会话,请参考《Amazon EC 起步指南》。

附录 A. 补充的引用

A.1. 从红帽 Customer Portal 下载文件

前提条件

  • 在开始这个任务前,你需要一个 Customer Portal 帐号。访问 https://access.redhat.com 并点击右上角的 Register 链接来创建帐号。

过程 A.1. 登录红帽 Customer Portal 并下载文件

  1. 访问 https://access.redhat.com 并点击右上角的 Log in 链接。输入用户密码然后点击 Log In
    结果

    你登录了 RHN 并位于主页位置 https://access.redhat.com

  2. 进入 Downloads 页面。

    使用下列选项来进入 Downloads 页面。
  3. 选择要下载的产品和版本。

    使用下列途径来选择要下载的产品和版本。
    • 逐级进行导航。
    • 通过屏幕右边的搜索区来搜索产品。
  4. 根据操作系统和安装方法下载合适的文件。

    根据你选择的产品,你可以选择 ZIP 归档、RPM、或特定操作系统和架构的原始安装程序。点击你要下载的文件右边的文件名或 Download 链接进行下载。
结果

文件将下载到你的电脑里。

A.2. 在红帽企业版 Linux 上配置默认的 JDK

在 Red Hat 企业版 Linux 上可以安装多个 JDK。这个任务向您展示如何指定当前环境使用的 JDK。它使用 alternatives 命令。

重要

这个任务只适用于 Red Hat 企业版 Linux。

注意

这个步骤也许不必要。Red Hat 企业版 Linux 将 OpenJDK 1.6 作为其默认选项。如果这就是您所要的,且您的系统运行正常,那您就不需要手动指定要使用的 JDK。

前提条件

  • 为了完成这个任务,您需要通过直接登录或者 sudo 命令具有超级用户权限。

过程 A.2. 配置默认的 JDK

  1. 确定您首选的 javajavac 执行文件的路径。

    您可以使用 rpm -ql packagename |grep bin 来查找从 RPM 安装的执行文件的位置。Red Hat 企业版 Linux 32 位系统上的 javajavac 执行文件的默认位置是:
    Expand
    表 A.1. java 和 javac 执行文件的默认位置
    JDK 路径
    OpenJDK 1.6
    /usr/lib/jvm/jre-1.6.0-openjdk/bin/java
    /usr/lib/jvm/java-1.6.0-openjdk/bin/javac
    Oracle JDK 1.6
    /usr/lib/jvm/jre-1.6.0-sun/bin/java
    /usr/lib/jvm/java-1.6.0-sun/bin/javac
  2. 设置您要使用的替代 JDK。

    运行下列命令设置您的系统来使用专有的 javajavac: /usr/sbin/alternatives --config java/usr/sbin/alternatives --config javac。请遵循屏幕上的说明进行。
  3. 可选项:设置 java_sdk_1.6.0 的替代选项。

    如果您想使用 Oracle JDK,你也需要为 java_sdk_1.6.0. 设置替代选项。请使用下列命令:/usr/sbin/alternatives --config java_sdk_1.6.0。正确的路径通常是 /usr/lib/jvm/java-1.6.0-sun
结果:

已选择并激活了替代 JDK。

附录 B. 修订历史记录

修订历史
修订 2.0-27.1Wed Jun 03 2015Xi Huang
update
修订 2.0-27Monday April 07 2014Lucas Costi
Red Hat JBoss Enterprise Application Platform 6.2.0.GA

法律通告

Copyright © 2015 Red Hat, Inc..
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

Theme

© 2026 Red Hat
返回顶部