第 3 章 JBoss EAP 的管理

JBoss EAP 使用了简化的配置,每个独立服务器或受管域对应一个配置文件。独立服务器的默认配置保存在 EAP_HOME/standalone/configuration/standalone.xml 文件,而受管域的默认配置保存在 EAP_HOME/domain/configuration/domain.xml 文件里。此外,主机控制器的默认配置保存在 EAP_HOME/domain/configuration/host.xml 文件里。

JBoss EAP 可以用命令行管理 CLI 或基于 Web 的管理控制台来配置。用这些管理界面进行的修改将自动持久化,XML 配置文件将被管理 API 重写。我们不推荐手动地编辑 XML 配置文件。

3.1. 关于子系统、扩展和配置集

JBoss EAP 功能的不同方面会在不同的子系统中进行配置。例如,应用程序和服务器的日志功能(logging)在 logging 子系统中配置。

子系统(subsystem)为一个特定的扩展提供配置选项。一个扩展(extension)就是一个模块,它被用来扩展服务器的核心功能。扩展会在需要时被加载,并在不需要时被卸载。

子系统配置的一组集合组成了一个配置集(profile),它被配置来满足服务器的需要。一个独立的服务器有一个单独的、没有命名的配置集。在一个受管域中可以定义多个配置集以供域中的服务器组使用。

如需了解更多与子系统相关的信息,请参阅 JBOSS EAP 子系统概述

使用管理控制台或管理 CLI

管理控制台和管理 CLI 都是有效的、受支持的更新 JBoss EAP 实例配置的方式。使用哪一个取决于您的喜好。喜欢使用图形化的、基于 Web 的界面的用户应该使用管理控制台。而偏好使用命令行的用户可以选择使用管理 CLI。

3.2. 管理用户

默认的 JBoss EAP 配置提供了本地用户身份验证功能,因此,一个用户可以在不需要请求验证的情况下访问本地主机上的管理 CLI。

但是,如果您需要远程访问 CLI 或使用管理控制台(使用管理控制台被认为是一个远程访问,即使它的网络数据是由本地产生的),则需要添加一个管理用户。如果您在添加管理用户前试图访问管理控制台,则会收到一个错误信息。

如果使用图形化安装程序安装 JBoss EAP,则在安装过程中会创建一个管理用户。

本指南涵盖了使用 add-user 脚本进行简单的 JBoss EAP 用户管理,这个脚本添加可立即验证的新用户至属性文件里。关于高级验证和授权选项,如 LDAP 或基于角色的访问控制(Role-Based Access Control ,RBAC),请参考《JBoss EAP 安全架构》里的核心管理验证章节。

3.2.1. 添加管理用户

  1. 运行 add-user 工具脚本并按提示进行。

    $ EAP_HOME/bin/add-user.sh
    注意

    对于 Windows 服务器,请使用 EAP_HOME\bin\add-user.bat 脚本。

  2. ENTER 选择默认的选项 a 来添加管理用户。

    这个用户将会添加至 ManagementRealm,并被授权通过管理控制台或管理 CLI 执行管理操作。另外一个选项(b)添加用户至 ApplicationRealm,它用于应用程序,并且没有特定的权限。

  3. 输入想要的用户名和密码,您会被提示确认密码。

    在默认情况下,JBoss EAP 允许弱密码,但会发出警告。关于修改这个默认行为的细节,请参考设置 Add-User 工具的密码限制

  4. 输入用户所属的用逗号隔开的组列表。如果不希望这个用户属于任何组,请按 ENTER 留空。
  5. 复查信息并输入 yes 确认。
  6. 确定这个用户是否代表远程的 JBoss EAP 服务器实例。关于基本的管理用户,请输入 no

    可能需要添加至 ManagementRealm 里的一种用户是代表其他 JBoss EAP 实例的用户,它能够通过验证以作为集群成员加入。如果是这样,请输入 yes,您将得到一个代表用户密码的哈希密码值,它将需要被添加到不同的配置文件里。

您也可以传入参数到 add-user 脚本非交互式地创建用户。我们不推荐在共享系统上使用这个方法,因为在日志和历史记录文件里可以看到密码。详情请参考非交互式地运行 Add-User 工具

3.2.2. 非交互式地运行 Add-User 工具

您可以在命令行传入参数,非交互式地运行 add-user 脚本。但最少您得提供用户名和密码。

警告

我们不推荐在共享系统上使用这个方法,因为在日志和历史记录文件里可以看到密码。

创建属于多个组的用户

下列命令添加了一个管理用户(mgmtuser1)和 guestmgmtgroup 组。

$ EAP_HOME/bin/add-user.sh -u 'mgmtuser1' -p 'password1!' -g 'guest,mgmtgroup'
指定替代的属性文件

在默认情况下,用 add-user 脚本创建的用户和组信息保存在位于服务器 configuration 目录下的属性文件里。

用户信息保存在下列属性文件里:

  • EAP_HOME/standalone/configuration/mgmt-users.properties
  • EAP_HOME/domain/configuration/mgmt-users.properties

组信息保存在下列属性文件里:

  • EAP_HOME/standalone/configuration/mgmt-groups.properties
  • EAP_HOME/domain/configuration/mgmt-groups.properties

这些默认的目录和属性文件名可以被覆盖。下列命令添加了一个新的用户,指定不同的名称和用户属性文件的位置。

$ EAP_HOME/bin/add-user.sh -u 'mgmtuser2' -p 'password1!' -sc '/path/to/standaloneconfig/' -dc '/path/to/domainconfig/' -up 'newname.properties'

新用户现在被添加到 /path/to/standaloneconfig/newname.properties/path/to/domainconfig/newname.properties 用户属性文件里。请注意,这些必须已经存在,否则您会看到错误信息。

如需获得 add-user 的完整参数列表,请使用 --help 参数,或参阅 ADD-USER 工具参数一节。

3.2.3. 设置 Add-User 工具的密码限制

add-user 工具脚本的密码限制可以用 EAP_HOME/bin/add-user.properties 文件进行配置。

在默认情况下,JBoss EAP 允许弱密码,但会发出警告。要拒绝不符合指定的最低要求的密码,请将 password.restriction 属性设置为 REJECT

EAP_HOME/bin/add-user.properties 文件里可以配置的其他密码要求:

  • 最小长度
  • 最少的字母字符
  • 最小数字
  • 最小符号
  • 禁止的密码列表(如 admin
  • 是否允许密码和用户名相同

3.3. 管理接口

3.3.1. 管理 CLI

管理命令行接口(Management Command-line Interface,CLI)是一个 JBoss EAP 命令行管理工具。

使用管理 CLI 来启动和停止服务器、部署和卸载应用程序、配置系统设置和执行其他管理性任务。操作可以批模式进行,允许将多个任务以组运行。

有许多常用的命令,例如 lscdpwd。管理 CLI 也支持 Tab 自动完成。

关于使用管理 CLI 的详情,包括命令和操作、语法和批模式运行,请参考《JBoss EAP 管理 CLI 指南》

启动管理 CLI
$ EAP_HOME/bin/jboss-cli.sh
注意

对于 Windows 服务器,请使用 EAP_HOME\bin\jboss-cli.bat 脚本。

连接到运行的服务器
connect

或者您可以通过 EAP_HOME/bin/jboss-cli.sh --connect 命令启动管理 CLI 并进行连接。

显示帮助

使用下列命令获得帮助。

help

使用下列命令获得关于某个命令的帮助。

deploy --help
退出管理 CLI
quit
查看系统设置

下列命令使用 read-attribute 操作显示是否启用了示例数据源。

/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
{
    "outcome" => "success",
    "result" => true
}

当运行在受管域时,您必须在命令前面使用 /profile=PROFILE_NAME 指定要更新的配置集。

/profile=default/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
更新系统设置

下列命令使用 write-attribute 操作来禁用示例数据源。

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled,value=false)
启动服务器

当运行在受管域里时,管理 CLI 也可以用于启动和停止服务器。

/host=HOST_NAME/server-config=server-one:start

3.3.2. 管理控制台

管理控制台是一个基于 Web 的 JBoss EAP 管理工具。

使用管理控制台来启动和停止服务器、部署和卸载应用程序、调优系统设置、永久地修改服务器配置文件。管理控制台也可以执行管理性任务,在当前用户进行的修改需要服务器实例重启或重载时发出即时通知。

在受管域里,相同域里的服务器实例和服务器组都可以通过域控制器的管理控制台集中管理。

对于在使用默认管理端口的本地主机上运行的 JBoss EAP 实例,管理控制台可以通过浏览器来访问:http://localhost:9990/console/App.html。您将需要用具有访问管理控制台权限的用户来进行验证。

管理控制台提供下列标签页来导航和管理您的 JBoss EAP 独立服务器或受管域。

主页
学习如何完成几个常见的配置和管理任务。体验控制台以熟悉它的使用。
部署
添加、删除和启用部署。在受管域里,分配部署到服务器组。
配置
配置可用的子系统,它提供 Web Service、消息或高可用性等功能。在受管域里,管理包含不同子系统配置的配置集。
运行时
查看运行时信息,如服务器状态、JVM 使用、服务器日志。在受管域里,管理您的主机、服务器组和服务器。
访问控制
当使用基于角色的访问控制时为用户和组分配角色。
补丁
应用补丁到您的 JBoss EAP 实例。
注意

要体验更新的管理控制台,请点击管理控制台主页上的 Take a Tour

要查看表单字段的细节,请点击 Need Help? 链接。

要查看您已执行的配置操作的历史记录,请点击管理控制台右上角的 Messages 链接。

3.3.2.1. 启用/禁用管理控制台

您可以通过 /core-service=management/management-interface=http-interface 资源里的 console-enabled 布尔值启用或禁用管理控制台。对于域模式里的主主机,是/host=master/core-service=management/management-interface=http-interface

例如,要启用控制台:

/core-service=management/management-interface=http-interface:write-attribute(name=console-enabled,value=true)

例如,要禁用控制台:

/core-service=management/management-interface=http-interface:write-attribute(name=console-enabled,value=false)

3.3.2.2. 修改管理控制台的语言设置

管理控制台的默认语言是英语。但您也可以选择下列语言:

  • 德语(de)
  • 简体中文(zh-Hans)
  • 巴西葡萄牙语(pt-BR)
  • 法语(fr)
  • 西班牙语(es)
  • 日语(ja)
要修改管理控制台的语言设置
  1. 登录管理控制台。
  2. 点击管理控制台右下角的 Settings 链接。
  3. Locale 选择框里选择想要的语言。
  4. 选择 Save。确认框会通知您需要重新加载应用程序。
  5. 点击 Confirm。系统会自动刷新您的浏览器以使用所选的语言。

3.4. 配置数据

3.4.1. 独立服务器的配置文件

The standalone configuration files are located in the EAP_HOME/standalone/configuration/ directory. A separate file exists for each of the four predefined profiles (default, ha, full, full-ha).

表 3.1. 独立配置文件

配置文件目的

standalone.xml

这个独立配置文件是您启动独立服务器时使用的默认配置。它包含所有关于服务器的信息,如子系统、网络、部署、套接字绑定和其他可配置细节。但它没有提供消息或高可用性所必需的子系统。

standalone-ha.xml

这个独立配置文件包括所有的默认子系统并添加了用于高可用性的 modclusterjgroups 子系统。它没有提供消息所必需的子系统。

standalone-full.xml

这个独立配置文件包括所有的默认子系统并添加了用于高可用性的 messaging-activemqiiop-openjdk 子系统。它没有提供高可用性所必需的子系统。

standalone-full-ha.xml

这个独立配置文件包括对任何子系统的支持,且也包括消息和高可用性所必需的子系统。

在默认情况下,将 JBoss EAP 作为独立服务器启动会使用 standalone.xml 文件。要用不同的配置启动 JBoss EAP,请使用 --server-config 参数。例如:

$ EAP_HOME/bin/standalone.sh --server-config=standalone-full.xml

3.4.2. 受管域配置文件

受管域配置文件位于 EAP_HOME/domain/configuration/ 目录。

表 3.2. 受管域配置文件

配置文件目的

domain.xml

这是用于受管域的主要配置文件。只有域主控制器会读取这个文件。它包含所有配置集的配置(defaulthafullfull-ha)。

host.xml

这个文件包括受管域里的物理主机所专有的配置细节,如网络接口、套接字绑定、主机名称和其他主机专有的细节。如下所示,host.xml 文件包括 host-master.xmlhost-slave.xml 的所有功能。

host-master.xml

这个文件只包括了一个服务器作为主域控制器运行所需的配置详情。

host-slave.xml

这个文件只包含将服务器作为受管域主机控制器运行所必需的配置细节。

在默认情况下,在受管域里启动 JBoss EAP 会使用 host.xml 文件。要用不同的配置启动 JBoss EAP,请使用 --host-config 参数。例如:

$ EAP_HOME/bin/domain.sh --host-config=host-master.xml

3.4.3. 备份配置数据

为了在以后恢复 JBoss EAP 服务器配置,您应该备份下列位置里的内容:

  • EAP_HOME/standalone/configuration/

    • 备份整个目录来保存独立服务器的用户数据、服务器配置和日志设置。
  • EAP_HOME/domain/configuration/

    • 备份整个目录来保存受管域的用户和配置集数据、域和主机配置及日志设置。
  • EAP_HOME/modules/

    • 备份任何自定义模块。
  • EAP_HOME/welcome-content/

    • 备份任何自定义欢迎内容。
  • EAP_HOME/bin/

    • 备份任何自定义脚本或启动配置文件。

3.4.4. 备份文件快照

为了协助服务器的维护和管理,JBoss EAP 在启动时创建了一个原始配置文件的带时间戳的版本。管理操作进行的任何额外的配置修改都将导致原始文件被自动备份,且保留实例的一个工作备份以供引用和回滚。此外,您也可以生成当前服务器配置的时间点拷贝,也就是配置快照。管理员可以保存和加载这些快照。

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

生成快照

使用管理 CLI 来生成当前配置的快照。

:take-snapshot
{
    "outcome" => "success",
    "result" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20151022-133109702standalone.xml"
}
列出快照

使用管理 CLI 列出所有已生成的快照。

:list-snapshots
{
    "outcome" => "success",
    "result" => {
        "directory" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot",
        "names" => [
            "20151022-133109702standalone.xml",
            "20151022-132715958standalone.xml"
        ]
    }
}
删除快照

使用管理 CLI 删除快照。

:delete-snapshot(name=20151022-133109702standalone.xml)
用快照启动服务器

服务器可以用快照或自动保存的配置启动。

  1. 进入 EAP_HOME/standalone/configuration/standalone_xml_history 目录并确定要加载的快照或配置文件。
  2. 启动服务器并指向所选的配置文件。传入相对于配置目录(EAP_HOME/standalone/configuration/)的相对路径。

    $ EAP_HOME/bin/standalone.sh --server-config=standalone_xml_history/snapshot/20151022-133109702standalone.xml
注意

当运行在受管域时,请使用 --host-config 参数来指定配置文件。

3.4.5. 查看配置修改

JBoss EAP 7 提供了对运行系统的配置修改进行跟踪的功能。这允许管理员查看其他授权用户进行的配置修改的历史记录。

重要

修改保存在内存里且在服务器重启时会丢失。这个功能不是对管理审计日志的替代。

要启用配置修改的跟踪,请使用下列管理 CLI 命令。您可以用 max-history 指定保存多少个条目。

/core-service=management/service=configuration-changes:add(max-history=10)

要查看最近的配置修改列表,请使用下列管理 CLI 命令。

/core-service=management/service=configuration-changes:list-changes

这将列出每个配置修改,包括日期、来源、结果和操作细节。例如,list-changes 命令的下列输出显示了配置修改,首先是最近的修改。

{
    "outcome" => "success",
    "result" => [
        {
            "operation-date" => "2016-02-12T18:37:00.354Z",
            "access-mechanism" => "NATIVE",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "address" => [],
                "operation" => "reload",
                "operation-headers" => {
                    "caller-type" => "user",
                    "access-mechanism" => "NATIVE"
                }
            }]
        },
        {
            "operation-date" => "2016-02-12T18:34:16.859Z",
            "access-mechanism" => "NATIVE",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "address" => [
                    ("subsystem" => "datasources"),
                    ("data-source" => "ExampleDS")
                ],
                "operation" => "write-attribute",
                "name" => "enabled",
                "value" => false,
                "operation-headers" => {
                    "caller-type" => "user",
                    "access-mechanism" => "NATIVE"
                }
            }]
        },
        {
            "operation-date" => "2016-02-12T18:24:11.670Z",
            "access-mechanism" => "HTTP",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "operation" => "remove",
                "address" => [
                    ("subsystem" => "messaging-activemq"),
                    ("server" => "default"),
                    ("jms-queue" => "ExpiryQueue")
                ],
                "operation-headers" => {"access-mechanism" => "HTTP"}
            }]
        }
    ]
}

这个例子列出影响配置的三个操作的细节:

  • 从管理 CLI 重载服务器。
  • 从管理 CLI 禁用 ExampleDS 数据源。
  • 从管理控制台删除 ExpiryQueue 队列。

3.4.6. 属性替换

JBoss EAP 允许您使用表达式来定义可替换属性来替换配置里的值。表达式使用格式 ${PARAMETER:DEFAULT_VALUE}。如果设置了指定的参数,参数的值将被使用。否则将使用默认值。

解析表达式所支持的来源是系统属性、环境变量和库。对于部署,来源可以是 META-INF/jboss.properties 文件里列出的属性。对于支持子部署的部署类型,如果属性文件位于外部部署(如 EAR),解析的作用域是全部子部署。如果属性文件位于某个子部署里,那么解析的作用域只是该子部署。

下面的 standalone.xml 配置文件将 public 接口的 inet-address 设置为 127.0.0.1,除非设置了 jboss.bind.address

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

用下列命令将 JBoss EAP 作为独立服务器启动时可以使用 jboss.bind.address 参数:

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=IP_ADDRESS
嵌套的表达式

表达式可以嵌套,这允许用更灵活的表达式替换固定值。嵌套表达式的格式和普通表达式类似,唯一不同是,一个表达式可以嵌套在另外的表达式中。例如:

${SYSTEM_VALUE_1${SYSTEM_VALUE_2}}

嵌套表达式是递归地进行求值的,所以里层的表达式会先进行求值,然后才是外层的表达式。表达式也可以是递归的,此时表达式会先解析为另外一个表达式,然后再进行解析。嵌套表达式在任何可以使用表达式的地方都可以使用,但管理 CLI 命令除外。

例如,如果要隐藏在数据源定义里使用的密码,您就可以使用嵌套表达式。数据源的配置可能有下列内容:

<password>${VAULT::ds_ExampleDS::password::1}</password>

ds_ExampleDS 的值可以用使用嵌套表达式的系统属性(datasource_name)替换。数据源的配置可以有下列内容:

<password>${VAULT::${datasource_name}::password::1}</password>

JBoss EAP 会首先对表达式 ${datasource_name} 求值,然后将结果放入更大的表达式并对结果表达式求值。这样配置的优势是数据源的名称可以独立于固定的配置。

基于描述符的属性替换

应用程序配置(如数据源连接参数)在部署、测试和产品环境里通常是不一样的。这种变化有时是通过构建系统脚本来处理,因为 Java EE 规格没有包含外部化这些配置的方法。在 JBoss EAP 里,您可以使用基于描述符的属性替换在外部管理配置。

基于描述符的属性替换通过描述符文件进行属性的替换,允许您从应用程序和构建链删除关于环境的假设。环境专有的配置可以通过部署描述符而不是注解或构建系统脚本来指定。您可以在文件里或通过命令行参数进行配置。

ee 子系统里有几个标记(flag)用来控制是否应用属性替换。

JBoss 专有的描述符替换是由 jboss-descriptor-property-replacement 标记控制的,它默认为 enabled。在启用后,属性可以在下列部署描述符里进行替换:

  • jboss-ejb3.xml
  • jboss-app.xml
  • jboss-web.xml
  • *-jms.xml
  • *-ds.xml

下列管理 CLI 命令可以用来启用或禁用 JBoss 专有描述符里的属性替换:

/subsystem=ee:write-attribute(name="jboss-descriptor-property-replacement",value=VALUE)

Java EE 描述符替换是由 spec-descriptor-property-replacement 标记控制的,它默认为 enabled。在启用后,属性可以在下列部署描述符里进行替换:

  • ejb-jar.xml
  • persistence.xml
  • application.xml
  • web.xml

下列管理 CLI 命令可以用来启用或禁用 Java EE 描述符里的属性替换:

/subsystem=ee:write-attribute(name="spec-descriptor-property-replacement",value=VALUE)

3.5. 文件系统路径

JBoss EAP 将逻辑名称用于文件系统路径。配置的其他部分然后通过逻辑名称引用这些路径,这避免了对每个实例使用绝对路径,也允许将专有的主机配置解析为统一的逻辑名称。

例如,默认的 logging 子系统配置将 jboss.server.log.dir 声明为服务器日志目录的逻辑名称。

示例:用于服务器日志目录的相对路径

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

JBoss EAP 自动提供大量的标准路径而无需用户在配置文件里进行配置。

表 3.3. 标准路径

属性描述

java.ext.dirs

Java 开发工具包扩展的目录。

java.home

Java 安装目录

jboss.controller.temp.dir

独立服务器和受管域的共用别名。它是用于临时文件存储的目录。等同于受管域里的 jboss.domain.temp.dir 和独立服务器上的 jboss.server.temp.dir

jboss.domain.base.dir

域内容的基础目录。

jboss.domain.config.dir

包含域配置的目录。

jboss.domain.data.dir

域用来存储持久性数据文件的目录。

jboss.domain.log.dir

域用来存储持久性日志文件的目录。

jboss.domain.temp.dir

域用来存储临时文件的目录。

jboss.domain.deployment.dir

域用来存储部署内容的目录。

jboss.domain.servers.dir

域用来存储受管域实例输出的目录。

jboss.home.dir

JBoss EAP 的根目录。

jboss.server.base.dir

独立服务器内容的基础目录。

jboss.server.config.dir

包含独立服务器配置的目录。

jboss.server.data.dir

独立服务器用来存储数据文件的目录。

jboss.server.log.dir

独立服务器用来存储日志文件的目录。

jboss.server.temp.dir

独立服务器用于临时文件存储的目录。

jboss.server.deploy.dir

独立服务器用来存储部署内容的目录。

user.dir

用户的当前工作目录。

user.home

用户的主目录。

您可以覆盖标准路径添加自定义路径

3.5.1. 覆盖标准路径

您可以覆盖以 jboss.server.*jboss.domain.* 开头的标准路径的默认位置。这可用两种方式来完成:

  • 启动服务器时传入命令行参数。例如:

    $ EAP_HOME/bin/standalone.sh -Djboss.server.log.dir=/var/log
  • 修改服务器配置文件里的 JAVA_OPTS 变量(standalone.confdomain.conf)。例如:

    JAVA_OPTS="$JAVA_OPTS -Djboss.server.log.dir=/var/log"
覆盖受管域的标准路径

这个例子的目标是将域文件存储到 /opt/jboss_eap/domain_data 目录,并自定义顶层目录的名称。这里使用默认的目录分组 by-server

  • 日志文件将保存在 all_logs 子目录里。
  • 数据文件将保存在 all_data 子目录里。
  • 临时文件将保存在 all_temp 子目录里。
  • 服务器的文件将保存在 all_servers 子目录里。

要实现这个配置,您可以在启动 JBoss EAP 时覆盖几个系统属性。

$ EAP_HOME/bin/domain.sh -Djboss.domain.temp.dir=/opt/jboss_eap/domain_data/all_temp -Djboss.domain.log.dir=/opt/jboss_eap/domain_data/all_logs -Djboss.domain.data.dir=/opt/jboss_eap/domain_data/all_data -Djboss.domain.servers.dir=/opt/jboss_eap/domain_data/all_servers

结果路径结构将是这样:

/opt/jboss_eap/domain_data/
               ├── all_data
               ├── all_logs
               ├── all_servers
               │   ├── server-one
               │   │   ├── data
               │   │   ├── log
               │   │   └── tmp
               │   └── server-two
               │       ├── data
               │       ├── log
               │       └── tmp
               └── all_temp

3.5.2. 添加自定义路径

您可以用管理 CLI 或管理控制台添加自定义文件系统路径。

  • 在管理 CLI 里,您可以用下列命令添加新的路径。

    /path=my.custom.path:add(path=/my/custom/path)
  • 在管理控制台里,您可以进入 Configuration 标签页并选择 Paths 来配置文件系统路径。在这里,您可以添加、修改和删除路径。

然后您可以开始使用这个自定义路径了。例如,下面的日志处理程序在它的相对路径里使用了自定义路径。

<subsystem xmlns="urn:jboss:domain:logging:3.0">
  ...
  <periodic-rotating-file-handler name="FILE" autoflush="true">
    <formatter>
      <named-formatter name="PATTERN"/>
    </formatter>
    <file relative-to="my.custom.path" path="server.log"/>
    <suffix value=".yyyy-MM-dd"/>
    <append value="true"/>
  </periodic-rotating-file-handler>
  ...
</subsystem>

3.5.3. 目录分组

在受管域里,每个服务器的文件都保存在 EAP_HOME/domain 目录里。您可以用主机控制器的 directory-grouping 属性指定如何组织子目录。目录可以根据服务器类型来分组。在默认情况下,目录是按服务器分组的。

按服务器进行目录分组

在默认情况下,目录是按服务器分组的。如果您的管理是以服务器为中心(server-centric) 的,我们推荐使用这种配置。例如,它允许对每个服务器实例配置备份和日志文件处理。

如果 JBoss EAP 是用 ZIP 方式安装的,其默认的目录结构(按服务器分组)将是这样的:

EAP_HOME/domain
         └─ servers
            ├── server-one
            │   ├── data
            │   ├── tmp
            │   └── log
            └── server-two
                ├── data
                ├── tmp
                └── log

要按服务器对域目录进行分组,请使用下列管理 CLI 命令:

/host=HOST_NAME:write-attribute(name=directory-grouping,value=by-server)

这将更新主机控制器的 host.xml 配置文件:

<servers directory-grouping="by-server">
  <server name="server-one" group="main-server-group"/>
  <server name="server-two" group="main-server-group" auto-start="true">
    <socket-bindings port-offset="150"/>
  </server>
</servers>
按类型进行目录分组

除了按服务器分组,您也可以按文件类型分组。如果您的管理是以文件类型为中心的(file type-centric),我们推荐这种配置,它允许您轻易地只备份数据文件。

如果 JBoss EAP 是用 ZIP 方式安装且域的文件是按类型分组的,那它的目录结构将是这样的:

EAP_HOME/domain
         ├── data
         │   └── servers
         │       ├── server-one
         │       └── server-two
         ├── log
         │   └── servers
         │       ├── server-one
         │       └── server-two
         └── tmp
             └── servers
                 ├── server-one
                 └── server-two

要按类型对域目录进行分组,请使用下列管理 CLI 命令:

/host=HOST_NAME:write-attribute(name=directory-grouping,value=by-type)

这将更新主机控制器的 host.xml 配置文件:

<servers directory-grouping="by-type">
  <server name="server-one" group="main-server-group"/>
  <server name="server-two" group="main-server-group" auto-start="true">
    <socket-bindings port-offset="150"/>
  </server>
</servers>

3.6. 系统属性

您可以使用 Java 系统属性来配置许多 JBoss EAP 选项,并设置应用服务器里使用的任何名称-值对。

系统属性可以用来覆盖 JBoss EAP 配置里的默认值。例如,下列公共接口绑定地址的 XML 配置展示了它可以通过 jboss.bind.address 系统属性设置,但如果没有提供系统属性,它将默认为 127.0.0.1

<inet-address value="${jboss.bind.address:127.0.0.1}"/>

在 JBoss EAP 里您可以通过多种方式设置系统属性,包括:

如果您使用 JBoss EAP 受管域,系统属性可以应用于整个域、专门的服务器组、某个主机及它的全部服务器实例、或者只是特定的服务器实例。和其他多数的 JBoss EAP 域设置一样,在更具体级别设置的系统属性将覆盖抽象的属性。详情请参考域管理章节。

在启动脚本里传入系统属性

您可以用 -D 参数将系统属性传入 JBoss EAP 启动脚本。例如:

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=192.168.1.2

对于在启动 JBoss EAP 之前需要设置的 JBoss EAP 选项,这种方法尤其有用。

用管理 CLI 设置系统属性

您可以用下列语法通过管理 CLI 设置系统属性:

/system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE)

例如:

/system-property=jboss.bind.address:add(value=192.168.1.2)

当用管理 CLI 设置系统属性时,某些 JBoss EAP 选项,包括上面的 jboss.bind.address 示例,都只有在服务器重启后才生效。

对于受管域,上面的例子为整个域配置了一个系统属性。您也可以在更具体的级别上覆盖系统属性。

用管理控制台设置系统属性

  • 对于独立服务器,您可以在管理控制台的 Configuration 标签页里配置系统属性。选择 System Properties,然后点击 View 按钮。
  • 对于受管域:

    • 域级别的系统属性可以在 Configuration 标签页里设置。选择 System Properties,然后点击 View 按钮。
    • 服务器组和服务器级别的系统属性可以在 Runtime 标签页里设置。选择要配置的服务器组或服务器,点击旁边的 View 按钮,然后选择 System Properties 标签页。
    • 主机级别的系统属性可以在 Runtime 标签页里设置。选择要配置的主机,然后在主机名旁的下拉菜单里,选择 Properties

用 JAVA_OPTS 设置系统属性

系统属性也可以用 JAVA_OPTS 环境变量来配置。修改 JAVA_OPTS 有许多方法,但 JBoss EAP 提供了一个配置文件来设置 JBoss EAP 进程使用的 JAVA_OPTS

对于独立服务器,这个文件是 EAP_HOME/bin/standalone.conf,对于受管域则是 EAP_HOME/bin/domain.conf。而 Microsoft Windows 系统里这些文件的扩展名都是 .bat

在相关的配置文件里添加您的 JAVA_OPTS 系统属性定义。下面的例子演示了在 Red Hat Enterprise Linux 系统里设置绑定地址。

  • 对于 standalone.conf,在文件结尾添加您的 JAVA_OPTS 系统属性定义。例如:

    ...
    # Set the bind address
    JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address=192.168.1.2"
  • 对于 domain.confJAVA_OPTS 必须在进程控制器的 JAVA_OPTS 之前设置。例如:

    ...
    # Set the bind address
    JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address=192.168.1.2"
    
    # The ProcessController process uses its own set of java options
    if [ "x$PROCESS_CONTROLLER_JAVA_OPTS" = "x" ]; then
    ...

3.7. 管理审计日志

您可以为管理接口启用审计日志,使用管理控制台、管理 CLI 或使用 Management API 的自定义应用程序执行的所有操作登记日志。审计日志条目以 JSON 格式保存。审计日志默认是禁用的。

您可以配置审计日志输出到文件syslog 服务器

注意

Login 和 logout 事件不能被审计,因为 JBoss EAP 里没有验证的会话。相反,审计消息是在从用户接收操作时登记日志的。

独立服务器日志审计

虽然默认是禁用的,默认的审计日志配置是写入到一个文件。

<audit-log>
    <formatters>
        <json-formatter name="json-formatter"/>
    </formatters>
    <handlers>
        <file-handler name="file" formatter="json-formatter" path="audit-log.log" relative-to="jboss.server.data.dir"/>
    </handlers>
    <logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="file"/>
        </handlers>
    </logger>
</audit-log>

这个配置可以用下列管理 CLI 命令读取。

/core-service=management/access=audit:read-resource(recursive=true)

关于启用代理服务器的审计日志,请参考启用审计日志

管理域审计日志

虽然默认是禁用的,默认审计日志配置为每台主机和服务器写入到一个文件。

<audit-log>
    <formatters>
        <json-formatter name="json-formatter"/>
    </formatters>
    <handlers>
        <file-handler name="host-file" formatter="json-formatter" relative-to="jboss.domain.data.dir" path="audit-log.log"/>
        <file-handler name="server-file" formatter="json-formatter" relative-to="jboss.server.data.dir" path="audit-log.log"/>
    </handlers>
    <logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="host-file"/>
        </handlers>
    </logger>
    <server-logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="server-file"/>
        </handlers>
    </server-logger>
</audit-log>

这个配置可以用下列管理 CLI 命令读取。

/host=HOST_NAME/core-service=management/access=audit:read-resource(recursive=true)

关于启用受管域的审计日志,请参考启用审计日志

3.7.1. 启用管理审计日志

JBoss EAP 预配置了用于审计日志的文件处理程序,虽然审计日志默认是禁用的。启用审计日志的管理 CLI 命令取决于 JBoss EAP 是作为独立服务器还是受管域运行的。关于文件处理程序的属性,请参考管理审计日志属性

要设立 syslog 审计日志,请参考设立管理审计日志到 Syslog 服务器

启用独立服务器日志审计

您可以用下列命令启用审计日志。

/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)

在默认情况下,这会将审计日志写入到 EAP_HOME/standalone/data/audit-log.log

启用受管域审计日志

受管域的默认审计日志配置是预配置为对每个主机和每台服务器写入审计日志的。

您可以用下列命令为每个主机启用审计日志。

/host=HOST_NAME/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)

在默认情况下,这会将审计日志写入到 EAP_HOME/domain/data/audit-log.log

您可以用下列命令为每台服务器启用审计日志。

/host=HOST_NAME/core-service=management/access=audit/server-logger=audit-log:write-attribute(name=enabled,value=true)

在默认情况下,这会将审计日志写入到 EAP_HOME/domain/servers/SERVER_NAME/data/audit-log.log

3.7.2. 发送管理审计日志到 Syslog 服务器

Syslog 处理程序指定发送日志条目至 Syslog 服务器使用的参数,特别是 Syslog 服务器侦听的主机名和端口。发送审计日志到 Syslog 服务器提供了一个比登录本地文件或 Syslog 服务器更安全的选项。您可以同时定义和激活多个 Syslog 处理程序。

在默认情况下,审计日志被预配置为在启用时输出到文件。使用下列步骤来设置并启用审计日志到 Syslog 服务器。关于 Syslog 处理程序的属性,请参考管理审计日志属性

  1. 添加 syslog 处理程序。

    创建 Syslog 处理程序,指定 Syslog 服务器的主机和端口。在受管域里,您必须在 /core-service 命令之前使用 /host=HOST_NAME

    batch
    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME:add(formatter=json-formatter)
    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME/protocol=udp:add(host=HOST_NAME,port=PORT)
    run-batch
    注意

    要传入的参数根据指定的协议的不同而不同。

    要配置处理程序使用 TLS 来与 Syslog 服务器安全地通讯,您也必须配置验证,例如:

    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME/protocol=tls/authentication=truststore:add(keystore-path=PATH_TO_TRUSTSTORE,keystore-password=TRUSTSTORE_PASSWORD)
  2. 添加对 Syslog 处理程序的引用。

    在受管域里,您必须在这个命令之前使用 /host=HOST_NAME

    /core-service=management/access=audit/logger=audit-log/handler=SYSLOG_HANDLER_NAME:add
  3. 启用审计日志。

    关于如何启用审计日志,请参考启用管理审计日志

重要

除非您也启用了操作系统里的日志,否则在 JBoss EAP 里启用审计日志至 Syslog 服务器无法成功。

关于 Red Hat Enterprise Linux 上 rsyslog 配置的更多信息,请参考 https://access.redhat.com/documentation/en/red-hat-enterprise-linux/《Red Hat Enterprise Linux 系统管理员指南》『Rsyslog 的基本配置』章节。

3.7.3. 读取审计日志条目

输出到文件的审计日志条目最好用文本查看器来查看,而输出到 Syslog 服务器的日志则最好使用 Syslog 查看器来查看。

注意

我们不推荐使用文件编辑器来查看日志文件,因为某些编辑器可能会阻止继续写入日志条目到日志文件里。

审计日志条目以 JSON 格式保存。每个日志条目都以可选的时间戳开始,后面跟着下表里的字段。

表 3.4. 管理审计日志的字段

字段名描述

access

它可以有这些值:

  • NATIVE - 操作通过原生管理接口进行。
  • HTTP - 操作通过域 HTTP 接口进行。
  • JMX - 操作通过 jmx 子系统进行。

booting

如果在引导过程中执行操作则为 true,如果在服务器已启动并运行时执行则为 false

domainUUID

当从域控制器传播到服务器、从主机控制器和从主机控制器服务器时,连接所有操作的 ID。

ops

正在执行的操作。这是序列换为 JSON 的操作列表。在引导时,这是解析 XML 所致的操作。引导后,这个列表通常包含单个条目。

r/o

如果操作没有修改管理模型,值为 true,否则值为 false

remote-address

执行这个操作的客户的地址。

success

如果操作成功则为 true,如果回滚则为 false

type

值可以为 core,表示这是一个管理操作;或者为 jmx,表示它来自 jmx 子系统。

user

已验证用户的用户名。如果使用管理 CLI 运行的操作在和运行服务器相同的主机上运行,特殊的用户 $local 将被使用。

version

JBoss EAP 实例的版本号。